manage.get.gov/docs/operations/runbooks/rotate_application_secrets.md

HOWTO Rotate the Application's Secrets

========================

Secrets are read from the running environment.

Secrets were originally created with:

cf cups getgov-credentials -p credentials-<ENVIRONMENT>.json

Where credentials-<ENVIRONMENT>.json looks like:

{
  "DJANGO_SECRET_KEY": "EXAMPLE",
  "DJANGO_SECRET_LOGIN_KEY": "EXAMPLE",
  "AWS_ACCESS_KEY_ID": "EXAMPLE",
  "AWS_SECRET_ACCESS_KEY": "EXAMPLE",
  ...
}

(Specific credentials are mentioned below.)

You can see the current environment with cf env <APP>, for example cf env getgov-stable.

The commands cups and uups stand for create user provided service and update user provided service. User provided services are the way currently recommended by Cloud.gov for deploying secrets. The user provided service is bound to the application in manifest-<ENVIRONMENT>.json.

To rotate secrets, create a new credentials-<ENVIRONMENT>.json file, upload it, then restage the app.

Example:

cf update-user-provided-service getgov-credentials -p credentials-stable.json
cf restage getgov-stable --strategy rolling

Non-secret environment variables can be declared in manifest-<ENVIRONMENT>.json directly.

DJANGO_SECRET_KEY

This is a standard Django secret key. See Django documentation for tips on generating a new one.

DJANGO_SECRET_LOGIN_KEY

This is the base64 encoded private key used in the OpenID Connect authentication flow with Login.gov. It is used to sign a token during user login; the signature is examined by Login.gov before their API grants access to user data.

Generate a new key using this command (or whatever is most recently recommended by Login.gov):

openssl req -nodes -x509 -days 365 -newkey rsa:2048 -keyout private.pem -out public.crt

Encode it using:

base64 private.pem

You also need to upload the public.crt key if recently created to the login.gov identity sandbox: https://dashboard.int.identitysandbox.gov/

AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY

To access the AWS Simple Email Service, we need credentials from the CISA AWS account for an IAM user who has limited access to only SES. Those credentials need to be specified in the environment.

REGISTRY_CL_ID and REGISTRY_PASSWORD

These are the login credentials for accessing the registry.

REGISTRY_CERT and REGISTRY_KEY and REGISTRY_KEY_PASSPHRASE

These are the client certificate and its private key used to identify the registrar to the registry during the establishment of a TCP connection.

The private key is protected by a passphrase for safer transport and storage.

These were generated with:

openssl genpkey -out client.key \
  -algorithm EC -pkeyopt ec_paramgen_curve:P-256 \
  -aes-256-cbc
openssl req -new -x509 -days 365 \
  -key client.key -out client.crt \
  -subj "/C=US/ST=DC/L=Washington/O=GSA/OU=18F/CN=GOV Prototype Registrar"

(If you can't use openssl on your computer directly, you can access it using Docker as docker run --platform=linux/amd64 -it --rm -v $(pwd):/apps -w /apps alpine/openssl.)

Encode them using:

base64 client.key
base64 client.crt

You'll need to give the new certificate to the registry vendor before rotating it in production.

REGISTRY_HOSTNAME

This is the hostname at which the registry can be found.