Skip to content

Commit

Permalink
Add Sigstore claimant model (#285)
Browse files Browse the repository at this point in the history
* Add Sigstore claimant model

The Sigstore claimant model formally defines a set of claims made by
Sigstore's two transparency logs. This was created in collaboration with
the creators of the claimant model.

This also includes sequence diagrams to make it easier to understand how
the various actors interact. These are a work in progress and generated
by a tool in Trillian.

Signed-off-by: Hayden Blauzvern <hblauzvern@google.com>

* Update rekor timestamp model verifier

Signed-off-by: Hayden Blauzvern <hblauzvern@google.com>

* Update rekor timestamp sequence diagram to remove verifier

Signed-off-by: Hayden Blauzvern <hblauzvern@google.com>

* Change CA to Fulcio, add generated comment

Signed-off-by: Hayden Blauzvern <hblauzvern@google.com>

* Clarify responsibility of Verifier

Signed-off-by: Hayden Blauzvern <hblauzvern@google.com>

* Update claimant to id/key owner

Signed-off-by: Hayden Blauzvern <hblauzvern@google.com>

---------

Signed-off-by: Hayden Blauzvern <hblauzvern@google.com>
  • Loading branch information
haydentherapper committed Jul 19, 2023
1 parent 0a37759 commit f7eadbe
Show file tree
Hide file tree
Showing 32 changed files with 757 additions and 0 deletions.
113 changes: 113 additions & 0 deletions docs/claimantmodel/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
# Sigstore Claimant Model

Sigstore's claimant model includes a set of claims produced by Rekor and Fulcio logs. See [Claimant Model](https://github.com/google/trillian/blob/master/docs/claimantmodel/CoreModel.md) for more information and terminology.

Sequence diagrams generated with [Claimant Model Render Tool](https://github.com/google/trillian/tree/master/docs/claimantmodel/experimental/cmd/render). This tool is a work in progress, so there may be some errors in the generated models.

Each claim is in `model.md` in each folder. `full.md` contains the claim made in both the domains of Rekor or Fulcio and the log. The sequence diagram shows the interactions between all Actors.

All claims are also provided in this readme.

## Fulcio: Identity-based signing

<dl>
<dt>Claim<sup>Fulcio</sup></dt>
<dd><i>${OIDCIDOwner} authorizes Fulcio to bind ${PubKey} to ${OIDCIdentity}</i></dd>
<dt>Statement<sup>Fulcio</sup></dt>
<dd>X.509 certificate containing ${PubKey} and ${OIDCIdentity}, signed by Fulcio</dd>
<dt>Claimant<sup>Fulcio</sup></dt>
<dd>Fulcio</dd>
<dt>Believer<sup>Fulcio</sup></dt>
<dd>Software Installer</dd>
<dt>Verifier<sup>Fulcio</sup></dt>
<dd>${OIDCIDOwner}: <i>${OIDCIDOwner} authorizes Fulcio to bind ${PubKey} to ${OIDCIdentity}. ${OIDCIDOwner} must actively look for Claims made on their behalf that they didn't knowingly authorize.</i></dd>
<dt>Arbiter<sup>Fulcio</sup></dt>
<dd>Community</dd>
</dl>

## Rekor: Identity-based signature

<dl>
<dt>Claim<sup>Rekor</sup></dt>
<dd><i>${OIDCIdentity} signs ${Hash} using the key bound by ${Certificate}</i></dd>
<dt>Statement<sup>Rekor</sup></dt>
<dd>${Hash}, X.509 certificate ${Certificate} containing ${OIDCIdentity}, and signature over ${Hash}</dd>
<dt>Claimant<sup>Rekor</sup></dt>
<dd>${OIDCIDOwner}</dd>
<dt>Believer<sup>Rekor</sup></dt>
<dd>Software Installer</dd>
<dt>Verifier<sup>Rekor</sup></dt>
<dd>${OIDCIDOwner}: <i>${OIDCIdentity} signs ${Hash} using the key bound by ${Certificate}. ${OIDCIDOwner} must actively look for Claims made on their behalf that they didn't knowingly authorize.</i></dd>
<dt>Arbiter<sup>Rekor</sup></dt>
<dd>Community, identity-artifact mapping</dd>
</dl>

## Rekor: Key-based signature

<dl>
<dt>Claim<sup>Rekor</sup></dt>
<dd><i>${Key} signs ${Hash}, verifiable with ${PubKey} </i></dd>
<dt>Statement<sup>Rekor</sup></dt>
<dd>${Hash}, public key ${PubKey}, and signature over ${Hash}</dd>
<dt>Claimant<sup>Rekor</sup></dt>
<dd>${KeyOwner}</dd>
<dt>Believer<sup>Rekor</sup></dt>
<dd>Software Installer</dd>
<dt>Verifier<sup>Rekor</sup></dt>
<dd>${KeyOwner}: <i>${Key} signs ${Hash}, verifiable with ${PubKey}. ${KeyOwner} must actively look for Claims made on their behalf that they didn't knowingly authorize.</i></dd>
<dt>Arbiter<sup>Rekor</sup></dt>
<dd>Community, key-artifact mapping</dd>
</dl>

## Rekor: Provenance

<dl>
<dt>Claim<sup>Rekor</sup></dt>
<dd><i>${OIDCIdentity} signs ${Provenance} containing ${Subject}, using the key bound by ${Certificate}</i></dd>
<dt>Statement<sup>Rekor</sup></dt>
<dd>${Provenance} with ${Hash}, X.509 certificate ${Certificate} containing ${OIDCIdentity}, signature over ${Subject}</dd>
<dt>Claimant<sup>Rekor</sup></dt>
<dd>${OIDCIDOwner}</dd>
<dt>Believer<sup>Rekor</sup></dt>
<dd>Software Installer</dd>
<dt>Verifier<sup>Rekor</sup></dt>
<dd>${OIDCIDOwner}/Artifact Builder: <i>${OIDCIdentity} signs ${Provenance} containing ${Subject}, using the key bound by ${Certificate}. ${OIDCIDOwner} or Artifact Builder must actively look for Claims made on their behalf that they didn't knowingly authorize.</i></dd>
<dt>Arbiter<sup>Rekor</sup></dt>
<dd>Community, identity-artifact mapping</dd>
</dl>

## Rekor: Timestamping

Note that this claim is a work in progress, as uploading signed timestamps is not yet supported in Rekor. See the [timestamping readme](rekor/timestamping/README.md) for more information.

<dl>
<dt>Claim<sup>Rekor</sup></dt>
<dd><i>Claim<sup>Rekor<sup>Identity</sup></sup> occurs at ${Timestamp}</i></dd>
<dt>Statement<sup>Rekor</sup></dt>
<dd>Signed ${Timestamp} over Statement<sup>Rekor<sup>Identity</sup></sup></dd>
<dt>Claimant<sup>Rekor</sup></dt>
<dd>${TSA}</dd>
<dt>Believer<sup>Rekor</sup></dt>
<dd>Software Installer</dd>
<dt>Verifier<sup>Rekor</sup></dt>
<dd>None: <i>Claim<sup>Rekor<sup>Identity</sup></sup> occurs at ${Timestamp}</i></dd>
<dt>Arbiter<sup>Rekor</sup></dt>
<dd>Community</dd>
</dl>

## Timestamp Authority

<dl>
<dt>Claim<sup>TSA</sup></dt>
<dd><i>${TimestampAuthority} claims a monotonically increasing ${Time}</i></dd>
<dt>Statement<sup>TSA</sup></dt>
<dd>Signed timestamp containing ${Time}</dd>
<dt>Claimant<sup>TSA</sup></dt>
<dd>${TimestampAuthority}</dd>
<dt>Believer<sup>TSA</sup></dt>
<dd>Software Installer, entity consuming short-lived code-signing certificate</dd>
<dt>Verifier<sup>TSA</sup></dt>
<dd>${TimestampMonotonicVerifier}: <i>${TimestampAuthority} claims a monotonically increasing ${Time}</i></dd>
<dt>Arbiter<sup>TSA</sup></dt>
<dd>Community</dd>
</dl>
31 changes: 31 additions & 0 deletions docs/claimantmodel/fulcio/identity/full.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<!--- This content generated with:
go run github.com/google/trillian/docs/claimantmodel/experimental/cmd/render@master --full_model_file ./docs/claimantmodel/fulcio/identity/full.yaml
-->
<dl>
<dt>Claim<sup>Fulcio</sup></dt>
<dd><i>${OIDCIDOwner} authorizes Fulcio to bind ${PubKey} to ${OIDCIdentity}</i></dd>
<dt>Statement<sup>Fulcio</sup></dt>
<dd>X.509 certificate containing ${PubKey} and ${OIDCIdentity}, signed by Fulcio</dd>
<dt>Claimant<sup>Fulcio</sup></dt>
<dd>Fulcio</dd>
<dt>Believer<sup>Fulcio</sup></dt>
<dd>Software Installer</dd>
<dt>Verifier<sup>Fulcio</sup></dt>
<dd>${OIDCIDOwner}: <i>${OIDCIDOwner} authorizes Fulcio to bind ${PubKey} to ${OIDCIdentity}</i></dd>
<dt>Arbiter<sup>Fulcio</sup></dt>
<dd>Community</dd>
</dl>
<dl>
<dt>Claim<sup>LOG_Fulcio</sup></dt>
<dd><i><ol><li>This data structure is append-only from any previous version</li><li>This data structure is globally consistent</li><li>This data structure contains only leaves of type `X.509 certificate containing ${PubKey} and ${OIDCIdentity}, signed by Fulcio`</li></ol></i></dd>
<dt>Statement<sup>LOG_Fulcio</sup></dt>
<dd>Log Checkpoint</dd>
<dt>Claimant<sup>LOG_Fulcio</sup></dt>
<dd>Log Operator</dd>
<dt>Believer<sup>LOG_Fulcio</sup></dt>
<dd><ul><li>Software Installer</li><li>${OIDCIDOwner}</li></ul></dd>
<dt>Verifier<sup>LOG_Fulcio</sup></dt>
<dd><ul><li>Witness: <i>This data structure is append-only from any previous version</i></li><li>Witness Quorum: <i>This data structure is globally consistent</i></li><li>${OIDCIDOwner}: <i>This data structure contains only leaves of type `X.509 certificate containing ${PubKey} and ${OIDCIdentity}, signed by Fulcio`</i></li></ul></dd>
<dt>Arbiter<sup>LOG_Fulcio</sup></dt>
<dd>Community</dd>
</dl>
26 changes: 26 additions & 0 deletions docs/claimantmodel/fulcio/identity/full.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
Domain:
System: Fulcio
Claimant: Fulcio
Statement: X.509 certificate containing ${PubKey} and ${OIDCIdentity}, signed by
Fulcio
Believer: Software Installer
Claim:
Claim: ${OIDCIDOwner} authorizes Fulcio to bind ${PubKey} to ${OIDCIdentity}
Verifier: ${OIDCIDOwner}
Arbiter: Community
Log:
System: LOG_Fulcio
Claimant: Log Operator
Statement: Log Checkpoint
Believers:
- Software Installer
- ${OIDCIDOwner}
Claims:
- Claim: This data structure is append-only from any previous version
Verifier: Witness
- Claim: This data structure is globally consistent
Verifier: Witness Quorum
- Claim: This data structure contains only leaves of type `X.509 certificate containing
${PubKey} and ${OIDCIdentity}, signed by Fulcio`
Verifier: ${OIDCIDOwner}
Arbiter: Community
25 changes: 25 additions & 0 deletions docs/claimantmodel/fulcio/identity/logsequence.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
<!--- This content generated with:
go run github.com/google/trillian/docs/claimantmodel/experimental/cmd/render@master --full_model_file ./docs/claimantmodel/fulcio/identity/full.yaml
-->
```mermaid
sequenceDiagram
actor Fulcio
actor ${OIDCIDOwner}
actor Log Operator
actor Software Installer
actor Witness
actor Witness Quorum
Fulcio->>Log Operator: Add new X.509 certificate containing ${PubKey} and ${OIDCIdentity}, signed by Fulcio
Log Operator->>Log Operator: Integrate X.509 certificate containing ${PubKey} and ${OIDCIdentity}, signed by Fulcios and issue Log Checkpoint
Log Operator->>Fulcio: Log Checkpoint and inclusion proof
Fulcio->>Software Installer: X.509 certificate containing ${PubKey} and ${OIDCIdentity}, signed by Fulcio with proof bundle
Software Installer->>Software Installer: Verify bundle and install software
loop Periodic append-only Verification
Witness->>Log Operator: Fetch merkle data
Witness->>Witness: Verify append-only
end
loop Periodic X.509 certificate containing ${PubKey} and ${OIDCIdentity}, signed by Fulcio Verification
${OIDCIDOwner}->>Log Operator: Get all entries
${OIDCIDOwner}->>${OIDCIDOwner}: Verify: ${OIDCIDOwner} authorizes Fulcio to bind ${PubKey} to ${OIDCIdentity}
end
```
17 changes: 17 additions & 0 deletions docs/claimantmodel/fulcio/identity/model.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<!--- This content generated with:
go run github.com/google/trillian/docs/claimantmodel/experimental/cmd/render@master --domain_model_file ./docs/claimantmodel/fulcio/identity/model.yaml
-->
<dl>
<dt>Claim<sup>Fulcio</sup></dt>
<dd><i>${OIDCIDOwner} authorizes Fulcio to bind ${PubKey} to ${OIDCIdentity}</i></dd>
<dt>Statement<sup>Fulcio</sup></dt>
<dd>X.509 certificate containing ${PubKey} and ${OIDCIdentity}, signed by Fulcio</dd>
<dt>Claimant<sup>Fulcio</sup></dt>
<dd>Fulcio</dd>
<dt>Believer<sup>Fulcio</sup></dt>
<dd>Software Installer</dd>
<dt>Verifier<sup>Fulcio</sup></dt>
<dd>${OIDCIDOwner}: <i>${OIDCIDOwner} authorizes Fulcio to bind ${PubKey} to ${OIDCIdentity}</i></dd>
<dt>Arbiter<sup>Fulcio</sup></dt>
<dd>Community</dd>
</dl>
8 changes: 8 additions & 0 deletions docs/claimantmodel/fulcio/identity/model.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
System: "Fulcio"
Claim:
Claim: "${OIDCIDOwner} authorizes Fulcio to bind ${PubKey} to ${OIDCIdentity}"
Verifier: "${OIDCIDOwner}"
Statement: "X.509 certificate containing ${PubKey} and ${OIDCIdentity}, signed by Fulcio"
Claimant: "Fulcio"
Believer: "Software Installer"
Arbiter: "Community"
31 changes: 31 additions & 0 deletions docs/claimantmodel/rekor/identity/full.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<!--- This content generated with:
go run github.com/google/trillian/docs/claimantmodel/experimental/cmd/render@master --full_model_file ./docs/claimantmodel/rekor/identity/full.yaml
-->
<dl>
<dt>Claim<sup>Rekor</sup></dt>
<dd><i>${OIDCIdentity} signs ${Hash} using the key bound by ${Certificate}</i></dd>
<dt>Statement<sup>Rekor</sup></dt>
<dd>${Hash}, X.509 certificate ${Certificate} containing ${OIDCIdentity}, and signature over ${Hash}</dd>
<dt>Claimant<sup>Rekor</sup></dt>
<dd>${OIDCIDOwner}</dd>
<dt>Believer<sup>Rekor</sup></dt>
<dd>Software Installer</dd>
<dt>Verifier<sup>Rekor</sup></dt>
<dd>${OIDCIDOwner}: <i>${OIDCIdentity} signs ${Hash} using the key bound by ${Certificate}</i></dd>
<dt>Arbiter<sup>Rekor</sup></dt>
<dd>Community, identity-artifact mapping</dd>
</dl>
<dl>
<dt>Claim<sup>LOG_Rekor</sup></dt>
<dd><i><ol><li>This data structure is append-only from any previous version</li><li>This data structure is globally consistent</li><li>This data structure contains only leaves of type `${Hash}, X.509 certificate ${Certificate} containing ${OIDCIdentity}, and signature over ${Hash}`</li></ol></i></dd>
<dt>Statement<sup>LOG_Rekor</sup></dt>
<dd>Log Checkpoint</dd>
<dt>Claimant<sup>LOG_Rekor</sup></dt>
<dd>Log Operator</dd>
<dt>Believer<sup>LOG_Rekor</sup></dt>
<dd><ul><li>Software Installer</li><li>${OIDCIDOwner}</li></ul></dd>
<dt>Verifier<sup>LOG_Rekor</sup></dt>
<dd><ul><li>Witness: <i>This data structure is append-only from any previous version</i></li><li>Witness Quorum: <i>This data structure is globally consistent</i></li><li>${OIDCIDOwner}: <i>This data structure contains only leaves of type `${Hash}, X.509 certificate ${Certificate} containing ${OIDCIdentity}, and signature over ${Hash}`</i></li></ul></dd>
<dt>Arbiter<sup>LOG_Rekor</sup></dt>
<dd>Community, identity-artifact mapping</dd>
</dl>
26 changes: 26 additions & 0 deletions docs/claimantmodel/rekor/identity/full.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
Domain:
System: Rekor
Claimant: ${OIDCIDOwner}
Statement: ${Hash}, X.509 certificate ${Certificate} containing ${OIDCIdentity},
and signature over ${Hash}
Believer: Software Installer
Claim:
Claim: ${OIDCIdentity} signs ${Hash} using the key bound by ${Certificate}
Verifier: ${OIDCIDOwner}
Arbiter: Community, identity-artifact mapping
Log:
System: LOG_Rekor
Claimant: Log Operator
Statement: Log Checkpoint
Believers:
- Software Installer
- ${OIDCIDOwner}
Claims:
- Claim: This data structure is append-only from any previous version
Verifier: Witness
- Claim: This data structure is globally consistent
Verifier: Witness Quorum
- Claim: This data structure contains only leaves of type `${Hash}, X.509 certificate
${Certificate} containing ${OIDCIdentity}, and signature over ${Hash}`
Verifier: ${OIDCIDOwner}
Arbiter: 'Community, identity-artifact mapping'
24 changes: 24 additions & 0 deletions docs/claimantmodel/rekor/identity/logsequence.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<!--- This content generated with:
go run github.com/google/trillian/docs/claimantmodel/experimental/cmd/render@master --full_model_file ./docs/claimantmodel/rekor/identity/full.yaml
-->
```mermaid
sequenceDiagram
actor ${OIDCIDOwner}
actor Log Operator
actor Software Installer
actor Witness
actor Witness Quorum
${OIDCIDOwner}->>Log Operator: Add new ${Hash}, X.509 certificate ${Certificate} containing ${OIDCIdentity}, and signature over ${Hash}
Log Operator->>Log Operator: Integrate ${Hash}, X.509 certificate ${Certificate} containing ${OIDCIdentity}, and signature over ${Hash}s and issue Log Checkpoint
Log Operator->>${OIDCIDOwner}: Log Checkpoint and inclusion proof
${OIDCIDOwner}->>Software Installer: ${Hash}, X.509 certificate ${Certificate} containing ${OIDCIdentity}, and signature over ${Hash} with proof bundle
Software Installer->>Software Installer: Verify bundle and install software
loop Periodic append-only Verification
Witness->>Log Operator: Fetch merkle data
Witness->>Witness: Verify append-only
end
loop Periodic ${Hash}, X.509 certificate ${Certificate} containing ${OIDCIdentity}, and signature over ${Hash} Verification
${OIDCIDOwner}->>Log Operator: Get all entries
${OIDCIDOwner}->>${OIDCIDOwner}: Verify: ${OIDCIdentity} signs ${Hash} using the key bound by ${Certificate}
end
```
17 changes: 17 additions & 0 deletions docs/claimantmodel/rekor/identity/model.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<!--- This content generated with:
go run github.com/google/trillian/docs/claimantmodel/experimental/cmd/render@master --domain_model_file ./docs/claimantmodel/rekor/identity/model.yaml
-->
<dl>
<dt>Claim<sup>Rekor</sup></dt>
<dd><i>${OIDCIdentity} signs ${Hash} using the key bound by ${Certificate}</i></dd>
<dt>Statement<sup>Rekor</sup></dt>
<dd>${Hash}, X.509 certificate ${Certificate} containing ${OIDCIdentity}, and signature over ${Hash}</dd>
<dt>Claimant<sup>Rekor</sup></dt>
<dd>${OIDCIDOwner}</dd>
<dt>Believer<sup>Rekor</sup></dt>
<dd>Software Installer</dd>
<dt>Verifier<sup>Rekor</sup></dt>
<dd>${OIDCIDOwner}: <i>${OIDCIdentity} signs ${Hash} using the key bound by ${Certificate}</i></dd>
<dt>Arbiter<sup>Rekor</sup></dt>
<dd>Community, identity-artifact mapping</dd>
</dl>
8 changes: 8 additions & 0 deletions docs/claimantmodel/rekor/identity/model.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
System: "Rekor"
Claim:
Claim: "${OIDCIdentity} signs ${Hash} using the key bound by ${Certificate}"
Verifier: "${OIDCIDOwner}"
Statement: "${Hash}, X.509 certificate ${Certificate} containing ${OIDCIdentity}, and signature over ${Hash}"
Claimant: "${OIDCIDOwner}"
Believer: "Software Installer"
Arbiter: "Community, identity-artifact mapping"
31 changes: 31 additions & 0 deletions docs/claimantmodel/rekor/key/full.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<!--- This content generated with:
go run github.com/google/trillian/docs/claimantmodel/experimental/cmd/render@master --full_model_file ./docs/claimantmodel/rekor/key/full.yaml
-->
<dl>
<dt>Claim<sup>Rekor</sup></dt>
<dd><i>${Key} signs ${Hash}, verifiable with ${PubKey}</i></dd>
<dt>Statement<sup>Rekor</sup></dt>
<dd>${Hash}, public key ${PubKey}, and signature over ${Hash}</dd>
<dt>Claimant<sup>Rekor</sup></dt>
<dd>${KeyOwner}</dd>
<dt>Believer<sup>Rekor</sup></dt>
<dd>Software Installer</dd>
<dt>Verifier<sup>Rekor</sup></dt>
<dd>${KeyOwner}: <i>${Key} signs ${Hash}, verifiable with ${PubKey}</i></dd>
<dt>Arbiter<sup>Rekor</sup></dt>
<dd>Community, key-artifact mapping</dd>
</dl>
<dl>
<dt>Claim<sup>LOG_Rekor</sup></dt>
<dd><i><ol><li>This data structure is append-only from any previous version</li><li>This data structure is globally consistent</li><li>This data structure contains only leaves of type `${Hash}, public key ${PubKey}, and signature over ${Hash}`</li></ol></i></dd>
<dt>Statement<sup>LOG_Rekor</sup></dt>
<dd>Log Checkpoint</dd>
<dt>Claimant<sup>LOG_Rekor</sup></dt>
<dd>Log Operator</dd>
<dt>Believer<sup>LOG_Rekor</sup></dt>
<dd><ul><li>Software Installer</li><li>${KeyOwner}</li></ul></dd>
<dt>Verifier<sup>LOG_Rekor</sup></dt>
<dd><ul><li>Witness: <i>This data structure is append-only from any previous version</i></li><li>Witness Quorum: <i>This data structure is globally consistent</i></li><li>${KeyOwner}: <i>This data structure contains only leaves of type `${Hash}, public key ${PubKey}, and signature over ${Hash}`</i></li></ul></dd>
<dt>Arbiter<sup>LOG_Rekor</sup></dt>
<dd>Community, key-artifact mapping</dd>
</dl>
Loading

0 comments on commit f7eadbe

Please sign in to comment.