-
Notifications
You must be signed in to change notification settings - Fork 69
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #164 from marcelamelara/docs-updates
Some more docs cleanup
- Loading branch information
Showing
4 changed files
with
45 additions
and
45 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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"}}}}} | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |