Skip to content

Commit

Permalink
Standardizing Fulcio Certificate Extensions
Browse files Browse the repository at this point in the history 
Co-authored-by: Phill MV <phillmv@github.com>
Signed-off-by: Philip Harrison <philip@mailharrison.com>
  • Loading branch information
@feelepxyz @phillmv
feelepxyz and phillmv committed Feb 14, 2023
1 parent b5172ca commit f9ae202
Show file tree
Hide file tree
Showing 2 changed files with 118 additions and 106 deletions.
72 changes: 0 additions & 72 deletions docs/deprecated-oid-info.md
View file

This file was deleted.

152 changes: 118 additions & 34 deletions docs/oid-info.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,69 +8,149 @@ code signing certificates issued by Fulcio instances. This document aims to
provide a simple directory of values in use with an explanation of their
meaning.

## Requirements to support signing with CI/CD workload identities

In order to support Sigstore code signing with CI/CD based workfload identities the following claims must be included in the OIDC ID Token. See example claim values for each extension in the detailed [Directory](#directory).

Requirements:

- MUST include `iss` claim for `Issuer` extension.
- MUST include claim to support: `Runner Environment` that differentiates between builds that took place in platform-hosted cloud infrastructure or customer-hosted infrastructure.
- MUST include claim to support: `Build Signer URI` that identifies the specific build instructions that are responsible for signing.
- MUST include claim to support: `Build Signer Digest` which is an immutable reference to a specific version of the build instructions that are responsible for signing.

Recommended:

- SHOULD include `iss` that uniquely identifies ID tokens originating from the CI/CD system, e.g. not shared with OIDC OAuth 2.0 tokens for email/username logins.
- SHOULD include claim to support: `Source Repository URI`
- SHOULD include claim to support: `Source Repository Digest`
- SHOULD include claim to support: `Source Repository Ref`
- SHOULD include claim to support: `Source Repository Identifier`
- SHOULD include claim to support: `Source Repository Owner URI`
- SHOULD include claim to support: `Source Repository Owner Identifier`

Nice-to-haves:

- MAY include claim to support: `Build Config URI`
- MAY include claim to support: `Build Config Digest`
- MAY include claim to support: `Build Trigger`
- MAY include claim to support: `Run Invocation URI`

## Terminology

- `Identifier`: Immutable resource identifier, e.g. uuid/primary key ID
- `URI`: SHOULD be a fully qualified URL when available. MAY be a mutable resource identifier, e.g. `https://scm.com/example/repository`
- Fully qualified URL: Complete URL with protocol.
- `Digest`: Immutable source repository reference, e.g. git commit SHA

## Directory

Note that all values begin from the root OID 1.3.6.1.4.1.57264 [registered by Sigstore][oid-link].

When adding additional OIDs under the root, please update the above link with the child OID.

GitHub Workflow specific OID extensions have been deprecated in favour of provider generic extensions starting from 1.3.6.1.4.1.57264.1.8.

## 1.3.6.1.4.1.57264.1 | Fulcio

The `.1` is added to the root OID for sigstore for all OIDs set by Fulcio.

### 1.3.6.1.4.1.57264.1.1 | Issuer

This contains the `issuer` claim from the OIDC Identity Token that was
This contains the `iss` claim from the OIDC Identity Token that was
presented at the time the code signing certificate was requested to be created.
This claim is the URI of the OIDC Identity Provider that digitally signed the
identity token. For example: https://token.actions.githubusercontent.com.
identity token. For example: `https://token.actions.githubusercontent.com`.

### 1.3.6.1.4.1.57264.1.2 | GitHub Workflow Trigger (deprecated)

This contains the `event_name` claim from the GitHub OIDC Identity token that
contains the name of the event that triggered the workflow run.
[(docs)][github-oidc-doc]

### 1.3.6.1.4.1.57264.1.3 | GitHub Workflow SHA (deprecated)

This contains the `sha` claim from the GitHub OIDC Identity token that contains
the commit SHA that the workflow run was based upon. [(docs)][github-oidc-doc]

### 1.3.6.1.4.1.57264.1.4 | GitHub Workflow Name (deprecated)

This contains the `workflow` claim from the GitHub OIDC Identity token that
contains the name of the executed workflow. [(docs)][github-oidc-doc]

### 1.3.6.1.4.1.57264.1.5 | GitHub Workflow Repository (deprecated)

This contains the `repository` claim from the GitHub OIDC Identity token that
contains the repository that the workflow run was based upon.
[(docs)][github-oidc-doc]

### 1.3.6.1.4.1.57264.1.6 | GitHub Workflow Ref (deprecated)

### 1.3.6.1.4.1.57264.3.1 | Source URI
This contains the `ref` claim from the GitHub OIDC Identity token that contains
the git ref that the workflow run was based upon.
[(docs)][github-oidc-doc]

### 1.3.6.1.4.1.57264.1.7 | OtherName SAN

This specifies the username identity in the OtherName Subject Alternative Name, as
defined by [RFC5280 4.2.1.6](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.6).


### 1.3.6.1.4.1.57264.1.8 | Source Repository URI

Should include a fully qualified source repository URL that the build was based
on.
on. For example: `example/repository`.

### 1.3.6.1.4.1.57264.3.2 | Source Digest
### 1.3.6.1.4.1.57264.1.9 | Source Repository Digest

An immutable reference to a specific version of the source code that the build
was based upon. Should include the digest type followed by the digest, e.g.
`sha1:abc123`.
was based upon. For example: `abc123` git commit SHA.

### 1.3.6.1.4.1.57264.3.3 | Source Ref
### 1.3.6.1.4.1.57264.1.10 | Source Repository Ref

The source ref that the build run was based upon. For example: `refs/head/main`.

### 1.3.6.1.4.1.57264.3.4 | Build Config URI
### 1.3.6.1.4.1.57264.1.11 | Source Repository Identifier

A reference to the initiating build instructions.
The immutable identifier for the source repository the workflow was based upon. For example: `1234` if using a primary key.

### 1.3.6.1.4.1.57264.3.5 | Build Config Digest
### 1.3.6.1.4.1.57264.1.12 | Source Repository Owner URI

An immutable reference to the specific version of the top-level build
instructions. Should include the digest type followed by the digest, e.g.
`sha1:abc123`.
Fully qualified URL for the owner of the source repository that the build was based
on, e.g. `example`

### 1.3.6.1.4.1.57264.3.6 | Build Siger URI
### 1.3.6.1.4.1.57264.1.13 | Source Repository Owner Identifier

Reference to specific build instructions that are responsible for signing. Can be the same as Build Config URI. For example a reusable workflow in GitHub Actions or a Circle CI Orbs.
The immutable identifier for the owner of the source repository that the workflow was based upon. For example: `5678` if using a primary key.

### 1.3.6.1.4.1.57264.1.14 | Build Config URI

### 1.3.6.1.4.1.57264.3.7 | Build Siger Digest
A reference to the initiating build instructions. For example: `example/repository/.github/workflows/publish.yml@refs/head/main`.

An immutable reference to the specific version of the build instructions that is responsible for signing. Should include the digest type followed by the digest, e.g. `sha1:abc123`.
### 1.3.6.1.4.1.57264.1.15 | Build Config Digest

An immutable reference to the specific version of the top-level build
instructions. For example: `abc123` git commit SHA.

### 1.3.6.1.4.1.57264.3.8 | Build Trigger
### 1.3.6.1.4.1.57264.1.16 | Build Signer URI

The event or action that triggered the build.
### 1.3.6.1.4.1.57264.3.9 | Runner Environment
Reference to specific build instructions that are responsible for signing. Can be the same as Build Config URI. Could be a reusable workflow ref in GitHub Actions or a Circle CI Orb name. For example: `slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@v1.4.0`.

For platforms to specify whether the build took place in platform-hosted cloud infrastructure or customer-hosted infrastructure. For example: `platform-hosted` and `self-hosted`.
### 1.3.6.1.4.1.57264.1.17 | Build Signer Digest

### 1.3.6.1.4.1.57264.1.7 | OtherName SAN
An immutable reference to the specific version of the build instructions that is responsible for signing. For example: `abc123` git commit SHA.

This specifies the username identity in the OtherName Subject Alternative Name, as
defined by [RFC5280 4.2.1.6](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.6).
### 1.3.6.1.4.1.57264.1.18 | Build Trigger

The event or action that triggered the build. For example: `push`.

### 1.3.6.1.4.1.57264.1.19 | Run Invocation URI

An immutable identifier that can uniquely identify the build execution. For GitHub Actions this needs to include both the run id and attempt. For example: `https://github.com/example/repository/actions/runs/1536140711/attempts/1`.

### 1.3.6.1.4.1.57264.1.20 | Runner Environment

For platforms to specify whether the build took place in platform-hosted cloud infrastructure or customer-hosted infrastructure. For example: `platform-hosted` and `self-hosted`.

## 1.3.6.1.4.1.57264.2 | Policy OID for Sigstore Timestamp Authority

Expand All @@ -81,19 +161,23 @@ that Sigstore operates.

| GitHub [(docs)][github-oidc-doc] | GitLab | CircleCI | Buildkite | Fulcio Certificate Extension | Why / Notes / Questions |
|--------------------|--------|----------|-----------|------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| aud | ?? | ?? | ?? | N/A | Only used to validate the JWT. |
| iss | ?? | ?? | ?? | Issuer | This already exists. For example: https://token.actions.githubusercontent.com |
| exp | ?? | ?? | ?? | N/A | Only used to validate the JWT. |
| nbf | ?? | ?? | ?? | N/A | Only used to validate the JWT. |
| iat | ?? | ?? | ?? | N/A | Only used to validate the JWT. |
| repository | ?? | ?? | ?? | Source URI | Should include a fully qualified repository URL. |
| sha | ?? | ?? | ?? | Source Digest | An immutable reference to a specific version of the source code. Should include the digest type followed by the digest, e.g. `sha1:abc123`. |
| ref | ?? | ?? | ?? | Source Ref | The source ref that the build run was based upon. For example: refs/head/main. |
| aud | ?? | aud | aud | N/A | Only used to validate the JWT. |
| iss | iss | iss | iss | Issuer | This already exists. For example: https://token.actions.githubusercontent.com |
| exp | exp | exp | exp | N/A | Only used to validate the JWT. |
| nbf | nbf | nbf | nbf | N/A | Only used to validate the JWT. |
| iat | iat | iat | iat | N/A | Only used to validate the JWT. |
| repository | project_path | ?? | ?? | Source Repository URI | Should include a fully qualified repository URL. |
| sha | ?? | ?? | build_commit | Source Repository Digest | An immutable reference to a specific version of the source code. Should include the digest type followed by the digest, e.g. `sha1:abc123`. |
| ref | ref | ?? | build_branch | Source Repository Ref | The source ref that the build run was based upon. For example: refs/head/main. |
| repository_id | project_id | ?? | ?? | Source Repository Identifier | Stable identifier for the owner of the source repository. |
| repository_owner | namespace_path | ?? | ?? | Source Repository Owner URI | Fully qualified URL for the owner of the source repository. |
| repository_owner_id | namespace_id | ?? | ?? | Source Repository Owner Identifier | Stable identifier for the owner of the source repository. |
| workflow_ref | ?? | ?? | ?? | Build Config URI | A reference to the initiating build instructions. |
| workflow_sha | ?? | ?? | ?? | Build Config Digest | An immutable reference to the specific version of the top-level build instructions. Should include the digest type followed by the digest, e.g. `sha1:abc123`. |
| job_workflow_ref | ?? | ?? | ?? | Build Signer URI | Reference to specific build instructions that are responsible for signing. Can be the same as Build Config URI. For example a reusable workflow in GitHub Actions or a Circle CI Orbs. |
| job_workflow_sha | ?? | ?? | ?? | Build Signer Digest | An immutable reference to the specific version of the build instructions that is responsible for signing. Should include the digest type followed by the digest, e.g. `sha1:abc123`. |
| event_name | ?? | ?? | ?? | Build Trigger | The event or action that triggered the build. |
| event_name | pipeline_source | ?? | ?? | Build Trigger | The event or action that triggered the build. |
| server_url + repository + "/actions/runs/" + run_id + "/attempts/" + run_attempt | ?? | ?? | ?? | Run Invocation URI | An immutable identifier that can uniquely identify the build execution |
| runner_environment | ?? | ?? | ?? | Runner Environment | For platforms to specify whether the build took place in platform-hosted cloud infrastructure or customer-hosted infrastructure. For example: `platform-hosted` and `self-hosted`. |

[github-oidc-doc]: https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token
Expand Down

0 comments on commit f9ae202

Please sign in to comment.