Skip to content

Commit d64965b

Browse files
ppkarwaszppkarwasz
committed
fix: improve documentation
1 parent 89d61d2 commit d64965b

1 file changed

Lines changed: 144 additions & 11 deletions

File tree

‎src/site/markdown/slsa/v0.1.0.md‎

Lines changed: 144 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,32 @@
66
"buildType": "https://commons.apache.org/proper/commons-release-plugin/slsa/v0.1.0"
77
```
88

9-
This is a [SLSA Build Provenance](https://slsa.dev/spec/v1.2/build-provenance) build type
10-
that describes releases produced by Apache Commons PMC release managers running Maven on their own equipment.
9+
This document defines a [SLSA v1.2 Build Provenance](https://slsa.dev/spec/v1.2/build-provenance) **build type** for
10+
releases of Apache Commons components.
11+
12+
Apache Commons releases are cut on a PMC release manager's workstation by invoking Maven against a checkout of the
13+
project's Git repository. The `commons-release-plugin` captures the build inputs and emits the result as an in-toto
14+
attestation covering every artifact attached to the project.
15+
16+
Because the build runs on the release manager's own hardware rather than on a hosted build service, the provenance
17+
corresponds to [SLSA Build Level 1](https://slsa.dev/spec/v1.2/levels): it is generated by the same process that
18+
produces the artifacts and is signed with the release manager's OpenPGP key, but the build platform itself is not
19+
separately attested.
20+
21+
The OpenPGP keys used to sign past and present artifacts are available at: https://downloads.apache.org/commons/KEYS
22+
23+
Attestations are published to Maven Central under the released artifact's coordinates, distinguished by an
24+
`intoto.jsonl` type:
25+
26+
```xml
27+
28+
<dependency>
29+
<groupId>org.apache.commons</groupId>
30+
<artifactId>${artifactId}</artifactId>
31+
<type>intoto.jsonl</type>
32+
<version>${version}</version>
33+
</dependency>
34+
```
1135

1236
## Build definition
1337

@@ -84,7 +108,7 @@ They are only present if the resource is accessible from Maven's Core Classloade
84108
|-------------------------|--------------------------------------------------------------|
85109
| `distributionId` | The ID of the Maven distribution. |
86110
| `distributionName` | The full name of the Maven distribution. |
87-
| `distributionShortName` | The short name of the Mavendistribution. |
111+
| `distributionShortName` | The short name of the Maven distribution. |
88112
| `buildNumber` | The Git commit hash from which this Maven release was built. |
89113
| `version` | The Maven version string. |
90114

@@ -115,14 +139,123 @@ It represents the commons-release-plugin acting as the build platform.
115139

116140
## Subjects
117141

118-
The attestation covers all artifacts attached to the Maven project at the time the `verify` phase runs:
119-
the primary artifact (e.g. the JAR) and any attached artifacts (e.g. sources JAR, javadoc JAR, POM).
120-
121-
| Field | Value |
122-
|-----------------|------------------------------------------|
123-
| `name` | Artifact filename. |
124-
| `uri` | Package URL. |
125-
| `digest.sha256` | SHA-256 hex digest of the artifact file. |
142+
The [`subject`](https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md#fields) array
143+
lists every artifact produces by the build. It has the following properties
144+
145+
| Field | Value |
146+
|----------|-------------------------------------------------------------------------------------------------------------------------------------|
147+
| `name` | Artifact filename in the default Maven repository layout, e.g. `commons-text-1.4-sources.jar`. |
148+
| `uri` | [Package URL](https://github.com/package-url/purl-spec) identifying the artifact in the `maven` namespace. |
149+
| `digest` | Map of [in-toto digest names](https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md) to hex-encoded digest values. |
150+
151+
By default, every subject carries `md5`, `sha1`, `sha256` and `sha512` digests.
152+
153+
## Example
154+
155+
The following is the bare attestation statement produced for the `commons-text` 1.4 release
156+
(abridged: most subjects are elided, and the JDK annotations trimmed). The full fixture lives at
157+
[`src/test/resources/attestations/commons-text-1.4.intoto.json`](https://github.com/apache/commons-release-plugin/blob/main/src/test/resources/attestations/commons-text-1.4.intoto.json)
158+
in the plugin source tree.
159+
160+
The statement shown below is wrapped in a [DSSE envelope](https://github.com/secure-systems-lab/dsse/blob/master/envelope.md)
161+
signed with the release manager's OpenPGP key, and the `.intoto.jsonl` file deployed to Maven Central
162+
contains that envelope.
163+
164+
```json5
165+
{
166+
"subject": [
167+
{
168+
"name": "commons-text-1.4.jar",
169+
"uri": "pkg:maven/commons-text/commons-text@1.4?type=jar",
170+
"digest": {
171+
"md5": "9cbe22bb0ce86c70779213dfb7f3eb5a",
172+
"sha1": "c81f089b3542485d4d09b02aae822906e5d2f209",
173+
"sha256": "ad2d2eacf15ab740c115294afc1192603d8342004a6d7d0ad35446f7dda8a134",
174+
"sha512": "126302c5f6865733774eb41fecc10ba8d0bb5ba11d14b9562047429abeb13bf8cdcdbfdf5e7d7708e2a40f67f4265cbbce609164f57abcd676067a840aa48e6a"
175+
}
176+
},
177+
// … one entry per attached artifact (POM, sources, javadoc, tests, and distribution archives) …
178+
{
179+
"name": "commons-text-1.4-src.zip",
180+
"uri": "pkg:maven/commons-text/commons-text@1.4?classifier=src&type=zip",
181+
"digest": {
182+
"md5": "fd65603e930f2b0805c809aa2deb1498",
183+
"sha1": "ca1cc6fbb4e46b44f8bb09b70c9e3a2ae3c5fce8",
184+
"sha256": "e4a6c992153faae4f7faff689b899073000364e376736b9746a5d0acb9d8b980",
185+
"sha512": "79ca61ff7b287407428bbb6ae13c6d372dcd0665114c55cd5bc57978a6fa760305e32feabef62cfeb0c4181220a59406239f6cccaa9a25c68773eef0250cb3a9"
186+
}
187+
}
188+
],
189+
"predicateType": "https://slsa.dev/provenance/v1",
190+
"predicate": {
191+
"buildDefinition": {
192+
"buildType": "https://commons.apache.org/builds/0.1.0",
193+
"externalParameters": {
194+
"maven.goals": ["deploy"],
195+
"maven.profiles": ["release"],
196+
"maven.user.properties": {
197+
"gpg.keyname": "3C8D57E0A2B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9"
198+
},
199+
"maven.cmdline": "deploy -Prelease -Dgpg.keyname=3C8D57E0A2B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9",
200+
"jvm.args": [
201+
"-Dfile.encoding=UTF-8",
202+
"-Dsun.stdout.encoding=UTF-8",
203+
"-Dsun.stderr.encoding=UTF-8"
204+
],
205+
"env": {
206+
"LANG": "pl_PL.UTF-8",
207+
"TZ": "UTC"
208+
}
209+
},
210+
"internalParameters": {},
211+
"resolvedDependencies": [
212+
// JDK that ran the build
213+
{
214+
"name": "JDK",
215+
"digest": { "gitTree": "bdb67e47c1b7df9c35ae045f29a348bb5bd32dc3" },
216+
"annotations": {
217+
"vendor": "Eclipse Adoptium",
218+
"vendor.version": "Temurin-25.0.2+10",
219+
"version": "25.0.2",
220+
"vm.name": "OpenJDK 64-Bit Server VM",
221+
"vm.version": "25.0.2+10-LTS"
222+
// … remaining java.* system properties elided …
223+
}
224+
},
225+
// Maven installation
226+
{
227+
"name": "Maven",
228+
"uri": "pkg:maven/org.apache.maven/apache-maven@3.9.12",
229+
"digest": { "gitTree": "3cdb4a67690dc18373f70ead98dc86567cc5ad67" },
230+
"annotations": {
231+
"distributionId": "apache-maven",
232+
"distributionName": "Apache Maven",
233+
"distributionShortName": "Maven",
234+
"buildNumber": "848fbb4bf2d427b72bdb2471c22fced7ebd9a7a1",
235+
"version": "3.9.12"
236+
}
237+
},
238+
// Source revision (branch or tag at release time)
239+
{
240+
"uri": "git+https://github.com/apache/commons-text.git@rel/commons-text-1.4",
241+
"digest": { "gitCommit": "f519b3670795da3fb4f43b6af1f727eadf8e6800" }
242+
}
243+
]
244+
},
245+
"runDetails": {
246+
"builder": {
247+
"id": "https://commons.apache.org/builds/0.1.0",
248+
"builderDependencies": [],
249+
"version": {}
250+
},
251+
"metadata": {
252+
"startedOn": "2026-04-20T09:28:44Z",
253+
"finishedOn": "2026-04-20T09:38:12Z"
254+
}
255+
}
256+
}
257+
}
258+
```
126259

127260
## Version history
128261

0 commit comments

Comments
 (0)