mirror of
https://github.com/cisagov/manage.get.gov.git
synced 2025-05-13 16:17:01 +02:00
104 lines
3.4 KiB
Markdown
104 lines
3.4 KiB
Markdown
# HOWTO Rotate the Application's Secrets
|
|
========================
|
|
|
|
Secrets are read from the running environment.
|
|
|
|
Secrets were originally created with:
|
|
|
|
```sh
|
|
cf cups getgov-credentials -p credentials-<ENVIRONMENT>.json
|
|
```
|
|
|
|
Where `credentials-<ENVIRONMENT>.json` looks like:
|
|
|
|
```json
|
|
{
|
|
"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`](https://docs.cloudfoundry.org/devguide/services/user-provided.html) 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:
|
|
|
|
```bash
|
|
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](https://developers.login.gov/testing/#creating-a-public-certificate)):
|
|
|
|
```bash
|
|
openssl req -nodes -x509 -days 365 -newkey rsa:2048 -keyout private.pem -out public.crt
|
|
```
|
|
|
|
Encode it using:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|