docs: added jvs docs (#114)

* added jvs docs * fixed nits * fixed feedback * fixed feedback * fixed format * fixed format * fixed feedback * fixed feedback * fixed format * fixed link * Update docs/jvs-quick-setup.md Co-authored-by: Chen Shou <cshou@google.com> Signed-off-by: capri-xiyue <52932582+capri-xiyue@users.noreply.github.com> Signed-off-by: capri-xiyue <52932582+capri-xiyue@users.noreply.github.com> Co-authored-by: Chen Shou <cshou@google.com>
abcxyz · Sep 8, 2022 · 9afe068 · 9afe068
1 parent 06f0d36
commit 9afe068
Show file tree

Hide file tree

Showing 8 changed files with 401 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -4,3 +4,31 @@
 
 This repository contains components related to a justification verification
 service
+
+## Use Case
+
+Audit logs are special logs that record `when` and `who` called `which`
+application and accessed `what` data. And `why` the access was necessary (aka.
+the justification of the data access). JVS is a solution to produce verified
+justifications and in combination with
+[abcxyz/lumberjack](https://github.com/abcxyz/lumberjack) the justifications
+could be audit logged.
+
+## Components
+
+JVS consists of the following components:
+
+*   JVS APIs
+    *   [Justification API](./cmd/justification): verify justifications and mint
+        short-lived justification tokens.
+    *   [Cert Rotator API](./cmd/cert-rotation): rotate signing
+        [keys](https://cloud.google.com/kms/docs/key-rotation).
+    *   [Public Key API](./cmd/public-key):
+        [JWKs](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets).
+*   [CLI Tool](./cmd/jvsctl)
+
+See manuals for [JVS APIs usage](./docs/jvs-apis.md) and
+[JVS CLI Tool Usage](./docs/cli-tool.md)
+
+**TODO(#115):** add a simple diagram to describe the user experience flow of
+enabling JVS in Lumberjack.
diff --git a/docs/cli-tool.md b/docs/cli-tool.md
@@ -0,0 +1,69 @@
+# CLI Tool
+
+**JVS is not an official Google product.**
+
+[jvsctl](../cmd/jvsctl) facilitates the justification verification flow provided
+by abcxyz/jvs
+
+## Install
+
+1.  Install jvsctl
+
+    ```shell
+    go install github.com/abcxyz/jvs/cmd/jvsctl
+    ```
+
+## Usage
+
+jvsctl [command]
+
+Run `jvsctl -h` for details of available flags.
+
+### Config
+
+Minimally we need a JVS server address in the config to mint justification
+tokens.
+
+```yaml
+server: example.com
+```
+
+By default, we will connect to the JVS server securely. When it's not applicable
+(e.g. locally run JVS server for testing), use insecure connection by adding the
+following block in the config:
+
+```yaml
+authentication:
+  insecure: true
+```
+
+Alternatively, both of these values could be provided via CLI flags `--server`
+and `--insecure`.
+
+## Command
+
+### jvsctl token [flags]
+
+To generate a justification token
+
+#### Flags
+
+Run `jvsctl token -h` for details
+
+#### Example
+
+```shell
+jvsctl token --explanation "issues/12345" --ttl 30m
+```
+
+The example above generates a signed justification token with 30m time-to-live
+duration and such token provide reasons that data access is required for
+"issues/12345"
+
+```shell
+jvsctl token --breakglass true --explanation "jvs is down" --ttl 30m
+```
+
+In certain cases, we might need to bypass JVS for minting signed JVS tokens.
+E.g. JVS couldn't verify a justification because the ticket system is down. In
+such cases, we can mint break-glass token instead.
diff --git a/docs/jvs-apis.md b/docs/jvs-apis.md
@@ -0,0 +1,55 @@
+# JVS APIs
+
+**JVS is not an official Google product.**
+
+## Justification API
+
+### API Spec
+
+Justification API is a [gRPC](https://grpc.io/) service. It accepts
+[CreateJustificationRequests](https://github.com/abcxyz/jvs/blob/main/protos/v0/jvs_request.proto#L23-L28)
+and responses with signed justification tokens as JWTs. See
+[JVSService](https://github.com/abcxyz/jvs/blame/e718d4664467b880991b8e2a400070c2aa93a0b9/blob/main/protos/v0/jvs_service.proto)
+for details.
+
+### Setup Knobs
+
+Justification API loads configs from environment variables. See
+[JustificationConfig](https://github.com/abcxyz/jvs/blob/main/pkg/config/justification_config.go#L32-L49)
+for details of supported config env variables.
+
+## Public Key API
+
+### API Spec
+
+Public Key API exposes a JWKS endpoint which is found at
+`${PUBLIC_KEY_SERVER_URL}/.well-known/jwks`. This endpoint will contain the JWK
+used to verify all Auth0-issued JWTs. Refer to
+[JWKs](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets).
+
+### Setup Knobs
+
+Public Key API loads configs from environment variables. See
+[PublicKeyConfig](https://github.com/abcxyz/jvs/blob/main/pkg/config/public_key_config.go#L26-L35)
+for details of supported config env variables.
+
+## Cert Rotation API
+
+### API Spec
+
+Cert Rotation API will do the following based on multiple conditions, see
+[RotateKey](https://github.com/abcxyz/jvs/blob/main/pkg/jvscrypto/rotation_handler.go#L42-L80)
+for details:
+
+*   Create new key versions
+*   Set the new primary key version
+*   Disable or delete old key versions
+
+The service is meant to be triggered by
+[Cloud Scheduler](https://cloud.google.com/scheduler) job.
+
+### Setup Knobs
+
+Cert Rotation API loads configs from environment variables. See
+[CryptoConfig](https://github.com/abcxyz/jvs/blob/main/pkg/config/crypto_config.go#L31-L51)
+for details of supported config env variables.
diff --git a/docs/jvs-quick-setup.md b/docs/jvs-quick-setup.md
@@ -0,0 +1,142 @@
+# JVS Setup
+
+**JVS is not an official Google product.**
+
+## Prerequisites
+
+you must have:
+
+*   An existing cloud org
+*   A billing account you can use in the cloud org
+*   A project you can use in the cloud org
+
+1.  Install [gcloud](https://cloud.google.com/sdk/docs/install)
+2.  make sure you are logged in with gcloud.
+
+    ```shell
+    gcloud auth login --update-adc
+    ```
+
+3.  Install [jvsctl](cli-tool.md/#install)
+
+## Set Up
+
+1.  Change directory to where terraform code lives
+
+    ```shell
+    cd terraform
+    ```
+
+2.  Copy an existing environment (e.g. quick-setup)
+
+    ```shell
+    cp -r quick-setup my-env && cd my-env
+    ```
+
+3.  When you create a new configuration or check out an existing configuration
+    from version control, you need to initialize the directory with:
+
+    ```shell
+    terraform init
+    ```
+
+4.  Time to apply
+
+    ```shell
+    terraform apply
+    ```
+
+    If you get a message like `The GCP project to host the justification
+    verification service`, please enter the GCP project where you want the JVS
+    system gets installed.
+
+5.  Wait until it’s done then you have a test environment up; there will be a
+    few outputs which you need to remember for later use. You will see output
+    similar to follows
+
+    ```shell
+    Outputs:
+    cert_rotator_server_url ="https://cert-rotator-e2e-xxxxx-uc.a.run.app"
+    jvs_server_url ="https://jvs-e2e-xxxx-uc.a.run.app"
+    public_key_server_url ="https://pubkey-e2e-xxxx-uc.a.run.app"
+    ```
+
+Besides above servers, [KMS](https://cloud.google.com/security-key-management)
+resources e.g.
+[keyRing](https://cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings)
+and
+[cryptoKey](https://cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys)
+will also get created.
+
+## Try JVS APIs
+
+### Justification API
+
+1.  Export the jvs server with the domain part of the `jvs_server_url` from
+    Terraform outputs like `jvs-e2e-xxxx-uc.a.run.app`
+
+    ```shell
+    export JVS_SERVER=<jvs_server_domain>:443
+    ```
+
+2.  Create Justification Token via [jvsctl](cli-tool.md):
+
+    ```shell
+    jvsctl token --explanation "issues/12345" --ttl 30m --server ${JVS_SERVER}
+    ```
+
+**TODO(#112):** Once we have the "validate token" command, we can even validate
+it.
+
+### Public Key API
+
+1.  Export the `public_key_server_url` from Terraform outputs
+
+    ```shell
+    export PUBLIC_KEY_SERVER_URL=<public_key_server_url>
+    ```
+
+2.  Fetch public keys via command:
+
+    ```shell
+    curl -H "Authorization: Bearer $(gcloud auth print-identity-token )" \
+    "${PUBLIC_KEY_SERVER_URL}/.well-known/jwks"
+    ```
+
+    You should see output similar to follows
+
+    ```shell
+    {"keys":[{"crv":"P-256","kid":"projects/test-project/locations/global/keyRings/ci-keyring/cryptoKeys/jvs-key/cryptoKeyVersions/1",
+    "kty":"EC","x":"u4SVWCYAZtD8J9r4bc150doTctTviIltS215qKkw8bF","y":"E3zbf_rvi7jTQykxcyUZqerXo_ssS6auvwR6mLchLll"},
+    {"crv":"P-256","kid":"projects/test-project/locations/global/keyRings/ci-keyring/cryptoKeys/jvs-key/cryptoKeyVersions/2",
+    "kty":"EC","x":"L4tcY2n2qKngEsLzatLXE_iTK39hUg18bE27H-r_p_M","y":"S0TrLBOPhyw7guoEIR2LSU6tLhelHLE3pZ4XaEJnzLN"}]}
+    ```
+
+### Cert Rotation API
+
+1.  Export the `cert_rotator_server_url` from Terraform outputs
+
+    ```shell
+    export CERT_ROTATOR_SERVER_URL=<cert_rotator_server_url>
+    ```
+
+2.  Rotate keys via command:
+
+    ```shell
+    curl -H "Authorization: Bearer $(gcloud auth print-identity-token )" \
+    "${CERT_ROTATOR_SERVER_URL}"
+    ```
+
+    You should see output similar to follows
+
+    ```shell
+    finished with all keys successfully.
+    ```
+
+## Clean up
+
+Run this command to tear down resources:
+
+```shell
+terraform destroy
+```
diff --git a/pkg/cli/token.go b/pkg/cli/token.go
@@ -44,7 +44,7 @@ var (
 var tokenCmd = &cobra.Command{
 	Use:     "token",
 	Short:   "To generate a justification token",
-	Example: `token --explanation "issues/12345" -ttl 30m`,
+	Example: `token --explanation "issues/12345" --ttl 30m`,
 	RunE:    runTokenCmd,
 }
 

diff --git a/terraform/quick-setup/main.tf b/terraform/quick-setup/main.tf
@@ -0,0 +1,54 @@
+/**
+ * Copyright 2022 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+resource "google_project_service" "serviceusage" {
+  project            = var.project_id
+  service            = "serviceusage.googleapis.com"
+  disable_on_destroy = false
+}
+
+resource "google_project_service" "services" {
+  project = var.project_id
+  for_each = toset([
+    "cloudresourcemanager.googleapis.com",
+    "iamcredentials.googleapis.com",
+    "artifactregistry.googleapis.com",
+  ])
+  service            = each.value
+  disable_on_destroy = false
+
+  depends_on = [
+    google_project_service.serviceusage,
+  ]
+}
+
+resource "google_artifact_registry_repository" "image_registry" {
+  provider = google-beta
+
+  location      = var.artifact_registry_location
+  project       = var.project_id
+  repository_id = "docker-images"
+  description   = "Container Registry for the images."
+  format        = "DOCKER"
+  depends_on = [
+    google_project_service.services["artifactregistry.googleapis.com"],
+  ]
+}
+
+module "jvs_e2e" {
+  source     = "../modules/jvs-e2e"
+  project_id = var.project_id
+  tag        = "e2e"
+}
diff --git a/terraform/quick-setup/outputs.tf b/terraform/quick-setup/outputs.tf
@@ -0,0 +1,26 @@
+/**
+ * Copyright 2022 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+output "jvs_server_url" {
+  value = module.jvs_e2e.jvs_server_url
+}
+
+output "public_key_server_url" {
+  value = module.jvs_e2e.public_key_server_url
+}
+
+output "cert_rotator_server_url" {
+  value = module.jvs_e2e.cert_rotator_server_url
+}