go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/server/secrets/doc.go (about)

     1  // Copyright 2015 The LUCI Authors.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  // Package secrets provides a secrets store based on Google Secret Manager.
    16  //
    17  // It supports stored and auto-generated secrets.
    18  //
    19  // Stored secrets are predefined blobs or texts (e.g. passwords or serialized
    20  // Tink keysets) that are placed in the Google Secret Manager and then read back
    21  // via this package. How secrets are written is outside the scope of this
    22  // package, it just reads them.
    23  //
    24  // Auto-generated secrets are random high-entropy strings with no inherent
    25  // structure. They are usually derived via a key derivation function from their
    26  // name and some root secret read from Google Secret Manager. They are useful
    27  // when calculating HMACs, as salts, etc.
    28  //
    29  // # Primary Tink AEAD key
    30  //
    31  // This package exposes functionality to encrypt/decrypt blobs using Tink AEAD
    32  // implementation. The reference to the encryption key in Google Secret Manager
    33  // is supplied via `-primary-tink-aead-key` flag. This key must be explicitly
    34  // initialized first.
    35  //
    36  // Create a new Google Secret Manager secret (with no values) named
    37  // `tink-aead-primary` in the cloud project that the server is running in
    38  // (referred to as `<cloud-project>` below). Make sure the server account has
    39  // "Secret Manager Secret Accessor" role in it. These steps are usually done
    40  // using Terraform.
    41  //
    42  // Initialize the key value by using
    43  // https://go.chromium.org/luci/server/cmd/secret-tool tool:
    44  //
    45  //	cd server/cmd/secret-tool
    46  //	go run main.go create sm://<cloud-project>/tink-aead-primary -secret-type tink-aes256-gcm
    47  //
    48  // This secret now contains a serialized Tink keyset with the primary encryption
    49  // key. Pass `-primary-tink-aead-key sm://tink-aead-primary` to the server
    50  // binary to tell it to use this key.
    51  //
    52  // If necessary the key can be rotated using the same `secret-tool` tool:
    53  //
    54  //	cd server/cmd/secret-tool
    55  //	go run main.go rotation-begin sm://<cloud-project>/tink-aead-primary
    56  //	# wait several hours for the new key to propagate into all caches
    57  //	# confirm by looking at /chrome/infra/secrets/gsm/version metric
    58  //	go run main.go rotation-end sm://<cloud-project>/tink-aead-primary
    59  //
    60  // This will add a new active key to the keyset. It will be used to encrypt
    61  // new plain text values, but the old key will still be recognized when
    62  // decrypting existing cipher texts until the next rotation occurs: at most one
    63  // old key version is retained currently.
    64  //
    65  // # The root secret
    66  //
    67  // The root secret is used to derive auto-generated secrets using HKDF. The
    68  // reference to the root secret key in Google Secret Manager is supplied via
    69  // `-root-secret` flag. This key must be explicitly initialized first.
    70  //
    71  // Create a new Google Secret Manager secret (with no values) named
    72  // `root-secret` in the cloud project that the server is running in (referred to
    73  // as `<cloud-project>` below). Make sure the server account has "Secret Manager
    74  // Secret Accessor" role in it. These steps are usually done using Terraform.
    75  //
    76  // Next create a new secret version with a randomly generated blob:
    77  //
    78  //	cd server/cmd/secret-tool
    79  //	go run main.go create sm://<cloud-project>/root-secret -secret-type random-bytes-32
    80  //
    81  // Pass `-root-secret sm://root-secret` to the server binary to tell it to use
    82  // this key.
    83  //
    84  // To rotate the key use the `secret-tool` again:
    85  //
    86  //	cd server/cmd/secret-tool
    87  //	go run main.go rotation-begin sm://<cloud-project>/root-secret
    88  //	# wait several hours for the new key to propagate into all caches
    89  //	go run main.go rotation-end sm://<cloud-project>/root-secret
    90  package secrets