diff --git a/content/en/logging/CLI.md b/content/en/logging/CLI.md index f8bcf720..407c862c 100644 --- a/content/en/logging/CLI.md +++ b/content/en/logging/CLI.md @@ -18,13 +18,13 @@ Before using Rekor, you are required to sign your release. The following example You may use either armored or plain binary: -``` +```bash gpg --armor -u jdoe@example.com --output mysignature.asc --detach-sig myrelease.tar.gz ``` You will also need to export your public key -``` +```bash gpg --export --armor "jdoe@example.com" > mypublickey.key ``` @@ -32,7 +32,7 @@ gpg --export --armor "jdoe@example.com" > mypublickey.key The `upload` command sends your public key / signature and artifact URL to the rekor transparency log. -``` +```bash rekor-cli upload --rekor_server https://rekor.sigstore.dev --signature --public-key --artifact | ``` @@ -40,7 +40,7 @@ The Rekor command will first verify your public key and signature and download a If the validations above pass correctly, the entry will be made to Rekor and an entry URL will be returned: -``` +```bash Created entry at: https://rekor.sigstore.dev/api/v1/log/entries/b08416d417acdb0610d4a030d8f697f9d0a718024681a00fa0b9ba67072a38b5 ``` @@ -50,10 +50,9 @@ This URL contains the UUID entry / merkle tree hash (in the above case `b08416d4 The `verify` command allows you to send a public key / signature and artifact to the Rekor transparency log for verification of entry. -You would typically use this command as a means to verify an 'inclusion proof' -showing that your artifact is stored within the transparency log. +You would typically use this command as a means to verify an 'inclusion proof' showing that your artifact is stored within the transparency log. -``` +```bash rekor-cli verify --rekor_server --signature --public-key --artifact | ``` @@ -63,11 +62,11 @@ rekor-cli verify --rekor_server --signature --p An entry in the log can be retrieved by using the `get` command with either the log index or the artifact UUID: -``` +```bash rekor-cli get --rekor_server https://rekor.sigstore.dev --log-index ``` -``` +```bash rekor-cli get --rekor_server https://rekor.sigstore.dev --uuid ``` @@ -75,7 +74,7 @@ rekor-cli get --rekor_server https://rekor.sigstore.dev --uuid The `loginfo` command retrieves the public key of the transparency log (unless already declared within the client `~/.rekor/rekor.yaml`) and then uses this public key to verify the signature on the signed tree head. -``` +```bash rekor-cli loginfo --rekor_server https://rekor.sigstore.dev ``` @@ -85,11 +84,12 @@ If running a redis instance within Rekor, the `search` command performs a redis This command requires one of an artifact, a public key, or a SHA hash (should be prefixed by `sha256:`). -``` +```bash rekor-cli search --rekor_server https://rekor.sigstore.dev --[artifact|public-key|sha] ``` For example: -``` + +```bash rekor-cli search --rekor_server https://rekor.sigstore.dev --sha sha256:e2e90d1a25f90a3156a27f00f3a4179578e3132ed4f010dc3498d09175b6071a ``` diff --git a/content/en/logging/installation.md b/content/en/logging/installation.md index c73e581a..cd444ba5 100644 --- a/content/en/logging/installation.md +++ b/content/en/logging/installation.md @@ -10,13 +10,13 @@ There are several ways to install both the `rekor-cli` and `rekor-server`. If you have Go installed, you can use go to retreive the `rekor-cli` binaries -``` +```bash go install -v github.com/sigstore/rekor/cmd/rekor-cli@latest ``` You may also do the same for `rekor-server`, but **please note** that the Rekor server also requires Trillian and a database. (see below for setup instructions). -``` +```bash go install -v github.com/sigstore/rekor/cmd/rekor-server@latest ``` @@ -28,10 +28,9 @@ Releases are available for both `rekor-server` and `rekor-cli`. Review [Verifying Binaries](/logging/verify-release/) for details on how to verify Rekor release binaries. - ## Build Rekor CLI manually -``` +```bash git clone https://github.com/sigstore/rekor.git rekor-cli cd rekor-cli make rekor-cli @@ -42,8 +41,8 @@ cp rekor-cli /usr/local/bin/ There are a few ways you can deploy a Rekor Server: -1. We have a [docker-compose](https://github.com/sigstore/rekor/blob/main/docker-compose.yml) file available. -2. Alternatively, you can build a Rekor server yourself. +1. We have a [docker-compose](https://github.com/sigstore/rekor/blob/main/docker-compose.yml) file available. +2. Alternatively, you can build a Rekor server yourself. Note: The Rekor server manually creates a new Merkle tree (or shard) in the Trillian backend every time it starts up, unless an existing one is specified in via the `--trillian_log_server.tlog_id` flag. If you are building the server yourself and do not need [sharding](/rekor/sharding/) functionality, you can find the existing tree's TreeID by issuing this client command while the server is running: @@ -73,25 +72,25 @@ Grab the Rekor source: Rekor requires a database. We use MariaDB for now (others to be explored later). Install and set up MariaDB on your machine. -``` +```bash dnf install mariadb mariadb-server systemctl start mariadb systemctl enable mariadb mysql_secure_installation ``` - + The Rekor directory has a `scripts/createdb.sh` file that will set up a test database (default user: test; default password: zaphod) and populate the needed tables for Trillian. If you’re just trying out Rekor, keep the DB user name and password the same as in the script (test/zaphod). If you change these, you need to make the changes on Trillian’s side (visit the [Trillian repo](https://github.com/google/trillian) for details). -``` +```bash cd $GOPATH/pkg/mod/github.com/sigstore/rekor@v0.4.0/scripts/ sh createdb.sh -``` - +``` + ### Build Trillian You also need to build Trillian, an append-only log: -``` +```bash go get -u -t -v github.com/google/trillian cd $GOPATH/src/github.com/google/trillian/cmd/trillian_log_server go build @@ -108,20 +107,21 @@ cp createtree /usr/local/bin/ Next, run the Trillian log server: -``` +```bash trillian_log_server --logtostderr ... ``` Run the signer: -``` +```bash trillian_log_signer --logtostderr --force_master --rpc_endpoint=localhost:8190 -http_endpoint=localhost:8191 --batch_size=1000 --sequencer_guard_window=0 --sequencer_interval=200ms ``` + > Note: you can log both to files and to stderr using `--alsologtostderr` Create the tree: -``` +```bash createtree --admin_server=localhost:8090 ``` @@ -129,7 +129,7 @@ createtree --admin_server=localhost:8090 With Trillian and MariaDB set up, you can now build the Rekor Server: -``` +```bash cd $GOPATH/pkg/mod/github.com/sigstore/rekor@v0.4.0/cmd/rekor-server go build -v -o rekor-server cp rekor-server /usr/local/bin/ @@ -137,14 +137,15 @@ cp rekor-server /usr/local/bin/ #### Start the Rekor Server -``` +```bash rekor-server serve --enable_retrieve_api=false -2020-09-12T16:32:22.705+0100 INFO cmd/root.go:87 Using config file: /Users/lukehinds/go/src/github.com/sigstore/rekor-server/rekor-server.yaml -2020-09-12T16:32:22.705+0100 INFO app/server.go:55 Starting server... -2020-09-12T16:32:22.705+0100 INFO app/server.go:61 Listening on 127.0.0.1:3000 +2020-09-12T16:32:22.705+0100 INFO cmd/root.go:87 Using config file: /Users/lukehinds/go/src/github.com/sigstore/rekor-server/rekor-server.yaml +2020-09-12T16:32:22.705+0100 INFO app/server.go:55 Starting server... +2020-09-12T16:32:22.705+0100 INFO app/server.go:61 Listening on 127.0.0.1:3000 ``` -> If you have a redis server running to enable searching your Rekor server, remove the `enable_reprieve_api` flag + +> If you have a redis server running to enable searching your Rekor server, remove the `enable_reprieve_api` flag #### Next Steps diff --git a/content/en/logging/overview.md b/content/en/logging/overview.md index d1cf6186..bdc988ee 100644 --- a/content/en/logging/overview.md +++ b/content/en/logging/overview.md @@ -20,21 +20,15 @@ Rekor fulfils the signature transparency role of sigstore’s software signing i You can download and setup the Rekor Server and Rekor CLI by following the instructions on the [Installation](/logging/installation/) page. -A public instance of Rekor can be found at [rekor.sigstore.dev](https://rekor.sigstore.dev). The public instance offers an SLO -of 99.5% availability and is monitored by an oncall team. +A public instance of Rekor can be found at [rekor.sigstore.dev](https://rekor.sigstore.dev). The public instance offers an SLO of 99.5% availability and is monitored by an oncall team. ## Auditing the Public Instance -Rekor is built on top of a [verifiable data structure](https://transparency.dev/verifiable-data-structures/). Auditors -can monitor the log for consistency, meaning that the log remains append-only and entries are never mutated or removed. +Rekor is built on top of a [verifiable data structure](https://transparency.dev/verifiable-data-structures/). Auditors can monitor the log for consistency, meaning that the log remains append-only and entries are never mutated or removed. Verifiers can also monitor the log for their identities. Learn more about transparency logs [here](https://transparency.dev/), and about binary transparency [here](https://binary.transparency.dev/). There are few options for auditing and monitoring the Rekor log. We've built a monitor that runs on GitHub Actions, -[Rekor monitor](https://github.com/sigstore/rekor-monitor). Follow the instructions to set up a new repository and -use the [provided reusable workflow](https://github.com/sigstore/rekor-monitor/blob/main/.github/workflows/reusable_monitoring.yml) -to audit the log. You can also monitor the log for specified identities, though -this feature is a work in progress and supports a limited set of identities and entry types. +[Rekor monitor](https://github.com/sigstore/rekor-monitor). Follow the instructions to set up a new repository and use the [provided reusable workflow](https://github.com/sigstore/rekor-monitor/blob/main/.github/workflows/reusable_monitoring.yml) to audit the log. You can also monitor the log for specified identities, though this feature is a work in progress and supports a limited set of identities and entry types. -You can also run [omniwitness](https://github.com/transparency-dev/witness/tree/main/cmd/omniwitness) to -audit the log, built by the team who created Trillian, which provides Rekor's verifiable log. +You can also run [omniwitness](https://github.com/transparency-dev/witness/tree/main/cmd/omniwitness) to audit the log, built by the team who created Trillian, which provides Rekor's verifiable log. diff --git a/content/en/logging/sign-upload.md b/content/en/logging/sign-upload.md index 14920384..a535a169 100644 --- a/content/en/logging/sign-upload.md +++ b/content/en/logging/sign-upload.md @@ -7,11 +7,14 @@ position: 835 This documentation contains information on how to sign and upload data in different [pluggable types](/logging/pluggable-types/). The following are covered: + - [Minisign](#minisign) - [SSH](#ssh) - [PKIX/X509](#pkixx509) -- RPM (TODO) -- TSR (TODO) +- [RPM](#rpm) +- [Alpine](#alpine) +- [RPM](#rpm-1) +- [TSR](#tsr) - [TUF](#tuf) ## Minisign @@ -160,7 +163,7 @@ writing EC key Sign the file with: ```console -$ openssl dgst -sha256 -sign ec_private.pem -out README.md.sig README.md +openssl dgst -sha256 -sign ec_private.pem -out README.md.sig README.md ``` Upload it to rekor with: @@ -220,15 +223,15 @@ Generate a TUF repository (for example, with the [Python reference implementatio With go-tuf: ```console -$ tuf init -$ tuf gen-key root -$ tuf gen-key targets -$ tuf gen-key snapshot -$ tuf gen-key timestamp -$ tuf add path/to/some/target.txt -$ tuf snapshot -$ tuf timestamp -$ tuf commit +tuf init +tuf gen-key root +tuf gen-key targets +tuf gen-key snapshot +tuf gen-key timestamp +tuf add path/to/some/target.txt +tuf snapshot +tuf timestamp +tuf commit ``` You will find the signed metadata in your TUF `repository/` directory: @@ -287,4 +290,3 @@ Body: { } ``` - diff --git a/content/en/logging/verify-release.md b/content/en/logging/verify-release.md index 486798a1..cf8f0ab2 100644 --- a/content/en/logging/verify-release.md +++ b/content/en/logging/verify-release.md @@ -25,30 +25,30 @@ For example, with binary `rekor-cli-linux-amd64`, also retrieve `rekor-cli-linux * `rekor-cli-linux-amd64_cert.pem`: The signing certificate. This is an X509 certificate generated by the sigstore root CA, with the email of a project maintainer embedded as a X509v3 Subject Alternative Name. This provides a guarantee that the binary was signed by the individual with access to that account (the email comes from an OpenID provider). In turn, this information is recorded into the transparency log so that the account can be monitored for misuse or compromise. * `rekor-cli-linux-amd64_signature.sig`: This is the signature generated as a result of the signing event. -#### Basic verify +### Basic verify With the above three files, we can now perform a rudimentary verification. We grab the public key from the signing cert: -``` -$ openssl x509 -pubkey -noout -in rekor-cli-linux-amd64_cert.pem > rekor-cli-linux-amd64_cert_public.pem +```sh +openssl x509 -pubkey -noout -in rekor-cli-linux-amd64_cert.pem > rekor-cli-linux-amd64_cert_public.pem ``` And then we verify: -``` +```sh $ openssl dgst -sha256 -verify rekor-cli-linux-amd64_cert_public.pem -signature rekor-cli-linux-amd64_signature.sig rekor-cli-linux-amd64 Verified OK ``` -#### Verify the certificate chain +### Verify the certificate chain We should check the trust chain against sigstore's Root CA. The root CA for Fulcio is currently: -``` +```bash -----BEGIN CERTIFICATE----- MIIB+DCCAX6gAwIBAgITNVkDZoCiofPDsy7dfm6geLbuhzAKBggqhkjOPQQDAzAq MRUwEwYDVQQKEwxzaWdzdG9yZS5kZXYxETAPBgNVBAMTCHNpZ3N0b3JlMB4XDTIx @@ -70,37 +70,37 @@ Save this locally to your machine as `fulcio-root.pem` Let's now validate the certificate chain: -``` +```sh $ openssl verify -verbose -no_check_time -CAfile fulcio-root.pem rekor-cli-linux-amd64_cert.pem rekor-cli-linux-amd64_cert.pem: OK ``` > 📓 We use `-no_check_time` as Fulcio certificates are short-lived (so they always will be expired by design!) -#### Verify the signing identity +### Verify the signing identity However, how do we know we can trust that public key is from a maintainer at sigstore? Let's look at mapping this to an identity: -``` +```sh $ openssl x509 -in rekor-cli-linux-amd64_cert.pem -noout -text |grep email email:ctadeu@gmail.com ``` OK, so we can see that a Fulcio-generated certificate, with a chain to the root certificate has the email identity of a sigstore maintainer (in this instance, our own release manager the awesome Carlos). -#### Verify the entry is in the transparency log +### Verify the entry is in the transparency log On the [release page](https://github.com/sigstore/rekor/releases) you will see some URLs, these are the rekor entries of the signing events. This is the link for the binary and signing materials we have been working with throughout this guide -https://rekor.sigstore.dev/api/v1/log/entries/b6fdc91e6af5bdd8df133802b7966aa53c1e59365741ee56e287f11263e02c33 +[https://rekor.sigstore.dev/api/v1/log/entries/b6fdc91e6af5bdd8df133802b7966aa53c1e59365741ee56e287f11263e02c33](https://rekor.sigstore.dev/api/v1/log/entries/b6fdc91e6af5bdd8df133802b7966aa53c1e59365741ee56e287f11263e02c33) Let's dig into this: -``` +```sh $ curl -X GET "https://rekor.sigstore.dev/api/v1/log/entries/b6fdc91e6af5bdd8df133802b7966aa53c1e59365741ee56e287f11263e02c33" | jq { @@ -140,7 +140,7 @@ $ curl -X GET "https://rekor.sigstore.dev/api/v1/log/entries/b6fdc91e6af5bdd8df1 Let's focus on the body and decode it from base64: -``` +```sh $ curl -X GET "https://rekor.sigstore.dev/api/v1/log/entries/b6fdc91e6af5bdd8df133802b7966aa53c1e59365741ee56e287f11263e02c33" | jq -r '.[].body'| base64 -d | jq -r '.[]' { @@ -162,26 +162,26 @@ $ curl -X GET "https://rekor.sigstore.dev/api/v1/log/entries/b6fdc91e6af5bdd8df1 Ok, now you can see the digest of the artifact that was signed: -``` +```sh $ sha256sum rekor-cli-linux-amd64 ce9a7c82f32194995888758cf107ef0cc52e0b8cdce73b4240658ee9e73783cb rekor-cli-linux-amd64 ``` We can then grab the signing certificate: -``` +```sh echo LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNrakNDQWhpZ0F3SUJBZ0lVQU0rK0dYRFN5bUNPSW82YmxMMG5EZngxb21nd0NnWUlLb1pJemowRUF3TXcKS2pFVk1CTUdBMVVFQ2hNTWMybG5jM1J2Y21VdVpHVjJNUkV3RHdZRFZRUURFd2h6YVdkemRHOXlaVEFlRncweQpNVEEzTWpnd09ETTNOREphRncweU1UQTNNamd3T0RVM05ERmFNQUF3ZGpBUUJnY3Foa2pPUFFJQkJnVXJnUVFBCklnTmlBQVJjMDMrUU4vTHBrOGpqUFQwTmV5a01ucm9mMnpZUkJxNm05ei9TMXhRSzduZnZhU3grRjUrTEtwN3gKR2ExbHY2SWNvRXdwUHA2MUdsYnd5S0VQVWJLdzJrYnJyRVpPMnhKV3kxb0VEUHBYMlJqcTBYS0RZcEF5Zi9mQwoyZzJjSnVtamdnRW5NSUlCSXpBT0JnTlZIUThCQWY4RUJBTUNCNEF3RXdZRFZSMGxCQXd3Q2dZSUt3WUJCUVVICkF3TXdEQVlEVlIwVEFRSC9CQUl3QURBZEJnTlZIUTRFRmdRVTRBUDhtTkI4ejhSZFJyTVVLZ1A2Mm0xUFErd3cKSHdZRFZSMGpCQmd3Rm9BVXlNVWRBRUdhSkNreVVTVHJEYTVLN1VvRzArd3dnWTBHQ0NzR0FRVUZCd0VCQklHQQpNSDR3ZkFZSUt3WUJCUVVITUFLR2NHaDBkSEE2THk5d2NtbDJZWFJsWTJFdFkyOXVkR1Z1ZEMwMk1ETm1aVGRsCk55MHdNREF3TFRJeU1qY3RZbVkzTlMxbU5HWTFaVGd3WkRJNU5UUXVjM1J2Y21GblpTNW5iMjluYkdWaGNHbHoKTG1OdmJTOWpZVE0yWVRGbE9UWXlOREppT1daallqRTBOaTlqWVM1amNuUXdIZ1lEVlIwUkFRSC9CQlF3RW9FUQpZM1JoWkdWMVFHZHRZV2xzTG1OdmJUQUtCZ2dxaGtqT1BRUURBd05vQURCbEFqRUE3TTJwSzhRUFRrSGs1bzZ0CmdnampZdjBLV1BUajRKUTAwU3RjR0xqa1g3SU1iNC9HdXpYRkQ4czZDOEd3NmpwMEFqQW1Xa2JROTVsMzlnUGQKR2pjUjBSQURaT0dYb0NPQURwOE5lSzhBL2dKdWdnR0ZINHZYZ2l1ODJsQm5MOEZSc09jPQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==| base64 -d > tlog_signing_cert.pem``` ``` Which is, of course, the same as our signing certificate: -``` -$ diff tlog_signing_cert.pem rekor-cli-linux-amd64_cert.pem +```sh +diff tlog_signing_cert.pem rekor-cli-linux-amd64_cert.pem ``` And the signature can also be retrieved: -``` +```sh echo MGUCMD3oKzgsGnPAkJEXegDIsdlh4BFCQbM6jng4Sy3axY/+2tlK97oe/CkxabT1ZXUqCAIxAJDq+zLfRZZEJD5DvaKhFEu+Jm+jD4UXc3CaZp2MSajiralmtalA6fSGCXjwGfUzOw== | base64 -d > tlog_signing_sig.sig $ diff tlog_signing_sig.sig rekor-cli-linux-amd64_signature.sig @@ -189,7 +189,7 @@ $ diff tlog_signing_sig.sig rekor-cli-linux-amd64_signature.sig So we can then do the same verification using just the tlog! -``` +```sh $ openssl x509 -pubkey -noout -in tlog_signing_cert.pem > tlog_signing_cert_public.pem $ openssl dgst -sha256 -verify tlog_signing_cert_public.pem -signature tlog_signing_sig.sig rekor-cli-linux-amd64 Verified OK diff --git a/content/en/signing/pkcs11.md b/content/en/signing/pkcs11.md index 8633404c..702474bb 100644 --- a/content/en/signing/pkcs11.md +++ b/content/en/signing/pkcs11.md @@ -10,8 +10,8 @@ This support is enabled through the [crypto11](https://github.com/ThalesIgnite/c For the following examples, we have: ```shell -$ IMAGE=gcr.io/vmtest2/demo -$ IMAGE_DIGEST=$IMAGE@sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd +IMAGE=gcr.io/vmtest2/demo +IMAGE_DIGEST=$IMAGE@sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd ``` ## Quick Start diff --git a/content/en/system_config/installation.md b/content/en/system_config/installation.md index 8447ef0e..32fc28f9 100644 --- a/content/en/system_config/installation.md +++ b/content/en/system_config/installation.md @@ -134,7 +134,7 @@ Before using Cosign, you will need to download and also initialize the TUF envir To do this, install and use [go-tuf](https://github.com/theupdateframework/go-tuf)'s CLI tools: ```console -$ go install github.com/theupdateframework/go-tuf/cmd/tuf-client@latest +go install github.com/theupdateframework/go-tuf/cmd/tuf-client@latest ``` Then, obtain trusted root keys for Sigstore. You will use the 5th iteration of Sigstore's TUF root to start the root of trust, due to a backward incompatible change. The TUF client uses this root to start a chain of roots, and will download the latest, unexpired root as part of [its workflow](https://theupdateframework.github.io/specification/latest/#update-root).