Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve docs for keyless SA signing #536

Merged
merged 1 commit into from
Aug 12, 2021
Merged

Improve docs for keyless SA signing #536

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 25 additions & 6 deletions KEYLESS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,9 +51,9 @@ The root CA keys are hard-coded in `cosign` today.
They can only be changed by recompiling the binary.
This will be made more configurable in the future.

### Oauth Flows
### OAuth Flows

Cosign supports two oauth flows today: the standard flow and the device flow.
Cosign supports two OAuth flows today: the standard flow and the device flow.

When there is no terminal attached (non-interactive mode), `cosign` will automatically use the device flow
where a link is printed to stdout.
Expand All @@ -63,14 +63,33 @@ This link must be opened in a browser to complete the flow.

In automated environments, cosign also supports directly using OIDC Identity Tokens from specific issuers.
These can be supplied on the command line with the `--identity-token` flag.
The `audiences` field must contain `fulcio`.
The `audiences` field must contain `sigstore`.

One example usage is:
#### On GCP

From a GCE VM, you can use the VM's service account identity to sign an image:

```shell
$ cosign sign --identity-token=$(gcloud auth print-identity-token --audiences=fulcio) gcr.io/dlorenc-vmtest2/demo
$ cosign sign --identity-token=$(
gcloud auth print-identity-token \
--audiences=sigstore) \
gcr.io/dlorenc-vmtest2/demo
```

From outside a GCE VM, you can impersonate a GCP IAM service account to sign an image:

```shell
$ cosign sign --identity-token=$(
gcloud auth print-identity-token \
--audiences=sigstore \
--include-email \
--impersonate-service-account [email protected]) \
gcr.io/dlorenc-vmtest2/demo
```

In order to impersonate an IAM service account, your account must have the
`roles/iam.serviceAccountTokenCreator` role.

### Timestamps

Signature timestamps are checked in the [rekor](https://github.com/sigstore/rekor) transparency log. Rekor's `IntegratedTime` is signed as part of its `signedEntryTimestamp`. Cosign verifies the signature over the timestamp and checks that the signature was created while the certificate was valid.
Expand Down Expand Up @@ -101,4 +120,4 @@ You can override the public good instance root CA using the enviromental variabl

```
export SIGSTORE_ROOT_FILE="/home/jdoe/myrootCA.pem"
```
```