Ctrl+K

Secrets, credentials, and passwords

Secrets, credentials, and passwords#

This section describes how 2i2c team members share and access sensitive credentials that allow permissions on our infrastructure and services.

Where are secrets located?#

For most services: Our team tries to use services that allow for multi-user authorization. This means we try to use services where team members have their own account with permissions on the service, so no secrets need be shared (for example, GitHub organizations).

When we must share secrets: If we must share secrets for an account (for example, credentails for deployment to cloud infrastructure), then we use the command-line tool sops to encrypt our secrets. See below for information about how to use sops.

We try to keep encrypted secrets files near their configuration files. For example, we’ll keep a Kubernetes configuration file in the same folder as the secrets that are needed to make changes to that cluster. See the 2i2c GKE cluster folder for an example.

sops overview#

sops is a command-line tool for encrypting and decrypting secrets that are on disk. It is similar to git-crypt (which is what is used by the Binder SRE team), but gives a bit more visibility into the encrypted fields by only encrypting the values rather than the keys.

Here’s an example of a file that has been encrypted with sops (from our infrastructure configuration):

grafana_token: ENC[AES256_GCM,data:o337Q5SSoBxk5bwSbbM12OO06LfLGsyWhh/SHccH4uOllMPSt4lN9EoRThfhDasrKaXyDmCNBdX+VBPrvBl1S61d7FG1Dfc/Cou3UODe99pZ53N1anooF5Oz38I=,iv:kai3CpHRtx1k9E5iZIcOOXFg0iElr7z+Q1+sZm6TNyI=,tag:1DfUibZUUIjaEMzpf0xkSw==,type:str]
sops:
  kms: []
  gcp_kms:
    - resource_id: projects/two-eye-two-see/locations/global/keyRings/sops-keys/cryptoKeys/similar-hubs
      created_at: "2021-10-18T17:21:01Z"
      enc: CiQA4OM7eCwqoRc3NEE62VoPH0gA0Po3esF12tQCnZPYegT5EeQSSQC9ZQbL4hYbnpjbvR0/ye+TTgW6I/0h4Ltv5uU2m5s+EQ4jLWLW/5oqpKIRyisqxQJaU42cFb6CeiII/117BEwXaGx0K+e+NDA=
  azure_kv: []
  hc_vault: []
  lastmodified: "2021-10-27T10:10:54Z"
  mac: ENC[AES256_GCM,data:rT4AaoBrRR9Ok4oB+ptLzMqdMecQxzIZqs2wXiPO5qazj20QyYlz2GCk5Szc8xw8itvjRh2G4SnbdWmNbtVvns3zTT1/OXtTTOiwAfVSYtMwF7hIxLYlMb1T/0RoYEmnxy8joa50+ClnHJk+cStcx0EF5ll1B++dpCMGP5oH/G4=,iv:r+TXdJZiPYP2kpSeiz2l1szvPXOZxSnns9GtTmHx1Xk=,tag:eaNOhcBdXYiBXdhrsqlW2g==,type:str]
  pgp: []
  unencrypted_suffix: _unencrypted
  version: 3.6.1

As you can see, we have access to the key names but the values are encrypted. Some information about which encryption key sops uses to encrypt/decrypt the secret is also stored under the top-level sops JSON key. In the next section we’ll cover how to unencrypt this file.

Set up sops#

To use sops with a 2i2c configuration file, follow these steps:

  1. Set up sops. To do so, follow the sops download and install instructions here.

  2. Set up the Google Cloud SDK. We use Google Cloud to provide the authentication for sops, and this is managed by the gcloud command-line tool. You will need access to the two-eye-two-see Google project in order to access the sops encryption keys. Follow the Google Cloud instructions to do so.

  3. Set up the Google Cloud Key Management Service (KMS). This allows you to use your Google Cloud login to provide authentication for sops. Follow the sops instructions to use KMS.

    Note

    This step is only required when setting up sops for the first time.

To confirm that sops has been set up properly, try encrypting or decrypting a configuration file per the sections below.

Decrypt secrets with sops#

In order to decrypt an encrypted configuration file, you should first follow the instructions in Set up sops. Once you’ve completed those steps, do the following:

  1. Navigate to the root of the repository. There are a set of rules stored in .sops.yaml that use regex to match a file to be encrypted with the encryption key location. You will receive an error from sops if you are not in the root folder and it cannot see this file.

  2. Run the sops command. The following command will decrypt a configuration file:

    sops --decrypt example/path/to/a/sops-file.yaml

    Tip

    You can also use the -d flag instead of --decrypt.

    You should see the decrypted configuration file printed to stdout.

    Secret file naming conventions

    We have naming conventions in place for our secret files that allow us to:

    1. Identify when a file is encrypted or not, and

    2. Use .gitignore rules to assist us in not committing unencrypted secrets to the repository

    See our infrastructure docs for more information on this.

Learn more about sops#

For more information about using sops, here are a few links to sops documentation:

2i2c-wide passwords#

For information about 2i2c-wide passwords, see Shared bitwarden account.

Contents