Merge pull request #164 from marcelamelara/docs-updates

Some more docs cleanup

README.md

@@ -2,8 +2,8 @@
 
 The in-toto Attestation Framework provides a specification for generating
 verifiable claims about any aspect of how a piece of software is produced.
-Consumers or users of software can then validate the origins of the
-software, and establish trust in its supply chain, using in-toto attestations.
+Consumers or users of software can then validate the origins of the software,
+and establish trust in its supply chain, using in-toto attestations.
 
 ## Learning about in-toto attestations
 
@@ -21,6 +21,9 @@ defines the format for in-toto attestations and the metadata they contain.
 We also provide a set of [attestation predicates], which are metadata
 formats vetted by our maintainers to cover a number of common use cases.
 
+For tooling integration, we provide [protobuf definitions] of the spec.
+We currently only provide a pre-generated library for Go.
+
 ## Is your use case not covered by existing predicate types?
 
 Take a look at the open [issues] or [pull requests] to see if your usage has
@@ -55,5 +58,6 @@ the framework. In the meantime, please visit any of the language-specific
 [in-toto]: https://in-toto.io
 [in-toto implementations]: https://github.com/in-toto
 [issues]: https://github.com/in-toto/attestation/issues?q=is%3Aopen+is%3Aissue
+[protobuf definitions]: docs/protos.md
 [pull requests]: https://github.com/in-toto/attestation/pulls?q=is%3Aopen+is%3Apr
 [specification]: spec/

docs/protos.md

@@ -1,33 +1,40 @@
-# Statement protobuf definitions
+# Spec protobuf definitions
 
-Protobuf definitions for the in-toto statement type and some predicates are provided in the
-spec/ directory.  Pre-generated Go implementation of those protos are available in the go dir.
+Protobuf definitions for the in-toto spec and some predicates are
+provided in the spec/ directory.  Pre-generated Go implementation of those
+protos are available in the go/ directory.
 
-go/example/main.go provides an example of how these protos can be used.
+## Pre-requisites
 
-To try it:
+On an Ubuntu-based system, install the following dependencies.
 
 ```shell
-$ make run
-...
-Read statement with predicateType https://example.com/unknownPred2
-Predicate fields:{key:"foo"  value:{struct_value:{fields:{key:"bar"  value:{string_value:"baz"}}}}}
+sudo apt install protobuf-compiler golang
 ```
 
-Please consider providing a proto version of any new predicates proposed.
-
 ## Regenerating Go proto libraries
 
 [It's typical to keep generated Go code in the repository itself](https://go.dev/doc/articles/go_command#:~:text=and%20then%20check%20those%20generated%20source%20files%20into%20your%20repository)
-since it makes users lives much easier.
+since it makes users' lives much easier.
 
-Proto libraries should be regenerated & commited after any change to the proto files:
+Proto libraries should be regenerated & commited after any change to the
+proto files:
 
 ```shell
 $ make go_protos
-go get google.golang.org/protobuf/cmd/[email protected]
-protoc --go_out=go --go_opt=paths=source_relative ./spec/predicates/vsa.proto ./spec/v1.0/statement.proto
 $ git commit -asm "update protos"
-[statement_proto 5edb2c6] Update protos
 ...
 ```
+
+## Run the Go example
+
+go/example/main.go provides an example of how these protos can be used.
+
+To try it:
+
+```shell
+$ make run
+...
+Read statement with predicateType https://example.com/unknownPred2
+Predicate fields:{key:"foo"  value:{struct_value:{fields:{key:"bar"  value:{string_value:"baz"}}}}}
+```

spec/predicates/README.md

@@ -12,17 +12,21 @@ community! Please see our [New Predicate Guidelines].
 This directory contains predicate specification types that have gone through
 our [vetting process], and may be of general interest:
 
--   [SLSA Provenance]: To describe the origins of a software artifact.
+-   [SLSA Provenance]: Describes how an artifact or set of artifacts was
+    produced.
 -   [Link]: For migration from [in-toto 0.9].
 -   [SCAI Report]: Evidence-based assertions about software artifact and
     supply chain attributes or behavior.
--   [Runtime Traces]: To capture runtime traces of software supply chain
+-   [Runtime Traces]: Captures runtime traces of software supply chain
     operations.
+-   [SLSA Verification Summary]: SLSA verification decision about a software
+    artifact.
 
 [Link]: link.md
 [New Predicate Guidelines]: ../../docs/new_predicate_guidelines.md
 [SCAI Report]: scai.md
 [SLSA Provenance]: https://slsa.dev/provenance
+[SLSA Verification Summary]: https://github.com/in-toto/attestation/blob/main/spec/predicates/vsa/vsa.md
 [in-toto 0.9]: https://github.com/in-toto/docs/blob/master/in-toto-spec.md#44-file-formats-namekeyid-prefixlink
 [vetting process]: ../../docs/new_predicate_guidelines.md#vetting-process
 [Runtime Traces]: runtime-trace.md

spec/v1.0/envelope.md

@@ -1,38 +1,23 @@
 # Envelope layer specification
 
-Version: v1.0
+Version: [DSSE v1.0]
 
 The Envelope is the outermost layer of the attestation, handling
-authentication and serialization. The format and protocol are defined in
-[DSSE] and adopted by in-toto in [ITE-5].
+authentication and serialization.
 
 ## Schema
 
-```jsonc
-{
-  "payloadType": "application/vnd.in-toto+json",
-  "payload": "<Base64(Statement)>",
-  "signatures": [{"sig": "<Base64(Signature)>"}]
-}
-```
+The format and protocol are defined per [DSSE v1.0].
 
 ## Fields
 
-`payloadType` _string, required_
+The in-toto Attestation Framework has the following requirements for the
+standard DSSE fields.
 
-> Identifier for the encoding of the payload. Always
-> `application/vnd.in-toto+json`, which indicates that it is a JSON object
-> with a `_type` field indicating its schema.
+-   `payloadType` MUST be set to `application/vnd.in-toto+json`, which
+    indicates that the Envelope contains a JSON object with a `_type` field
+    specifying its schema.
+-   `payload` MUST be a base64-encoded JSON [Statement].
 
-`payload` _string, required_
-
-> Base64-encoded JSON [Statement].
-
-`signatures` _array of objects, required_
-
-> One or more signatures over `payloadType` and `payload`, as defined in
-> [DSSE].
-
-[DSSE]: https://github.com/secure-systems-lab/dsse
-[ITE-5]: https://github.com/in-toto/ITE/blob/master/ITE/5/README.adoc
+[DSSE v1.0]: https://github.com/secure-systems-lab/dsse/blob/v1.0.0/envelope.md
 [Statement]: statement.md