cleanup artifact configuration attestation docs

Author: stefan-wenig

docs/_data/tables/artifact-configuration.yml

@@ -383,3 +383,27 @@ similar-directories-example-match:
 
         (All `msi`, `exe` and `dll` files are signed with Authenticode.)
       image: "![graphical resolved artifacts](/assets/img/resources/artifact-configuration/artifact-configuration_similar-resolved.png)"
+
+attestation-directives:
+  headers:
+    directive: Directive
+    parameter: Parameter
+    description: Description
+  body:
+    - directive: "`<create-provenance-file>`"
+      parameter: "`output-file-name`"
+      description: File name for the provenance statement.
+    - directive: "`<create-verification-summary-file>`"
+      parameter: "`output-file-name`"
+      description: File name for the verification summary statement.
+    - directive: "`<create-attestation-signature>`"
+      parameter: "`type`"
+      description: |
+        Signature type. Currently supported: [`cms`](reference/#create-cms-signature) and [`dsse`](reference/#dsse-sign).
+      _attributes:
+        directive: {rowspan: 2}
+    - directive: "$skip"
+      parameter: "`output-file-name`"
+      description: File name for the attestation signature.
+    - directive: "`<include-in-provenance>`"
+      parameter: "*none*"

docs/_includes/render-table.html

@@ -48,7 +48,7 @@
                     <tr>
                         {%- for cell in include.table.headers -%}
                             {%- assign columnId = cell[0] -%}
-                            {%- unless columnId == "_attributes" or table-omit-columns contains columnId -%}
+                            {%- unless columnId == "_attributes" or table-omit-columns contains columnId or row[columnId] == "$skip" -%}
                                 <td markdown="1" {% for attribute in row._attributes[columnId] %} {{ attribute[0] }}="{{ attribute[1] }}" {% endfor %} >
 {{ row[columnId] }}
 </td>

docs/artifact-configuration/attestations.md

@@ -11,23 +11,18 @@ datasource: tables/artifact-configuration
 
 SignPath can create SLSA attestations for any of the supported build systems. See the [definition](/slsa-attestations) for more details.
 
-Creating a SLSA attestation requires multiple directives:
+Creating a SLSA statement requires multiple directives:
 
-* `<include-in-provenance>` to include a reference to a file in the generated provenance.
-* `<create-provenance-file>` inside a root level `<zip-file>` to create a SLSA provenance.
-* `<create-verification-summary-file>` to create a SLSA verification summary.
-* `<create-attestation-signature>` to sign the provenance and turn them into a SLSA attestation or SLSA verification summary attestation (VSA).
+* Add `<create-provenance-file>` to the root level `<zip-file>` to create a SLSA provenance statement.
+* Add `<create-verification-summary-file>` to the `<create-provenance-file>` element to create a SLSA verification summary statement.
+* Sign both by adding a `<create-attestation-signature>` to each. Signing effectively turns the statements into proper attestations.
+* Add `<include-in-provenance>` to each file that you want to include generated provenance's subject section.
 
-The parameters for all these directives, except `<include-in-provenance>`, which does not have any, are listed below.
+Supported parameters:
 
-| Directive                            | Parameter          | Description
-|-----------                           |-----------         |-------------------------------------------------
-| `<create-provenance-file>`           | `output-file-name` | Name of the output file to hold the provenance information.
-| `<create-verification-summary-file>` | `output-file-name` | Name of the output file to hold the verification summary information.
-| `<create-attestation-signature>`     | `type`             | The signature type. Currently supported are [`cms`](#create-cms-signature) and [`dsse`](#dsse-sign).
-| `<create-attestation-signature>`     | `output-file-name` | Name of the output file to hold the attestation signature.
+{%- include render-table.html table=site.data.tables.artifact-configuration.attestation-directives -%}
 
-#### Example
+### Example
 
 ~~~ xml
 <artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
@@ -39,13 +34,13 @@ The parameters for all these directives, except `<include-in-provenance>`, which
       <create-attestation-signature type="cms" output-file-name="${file.name}.cms.pem" />
       <create-verification-summary-file output-file-name="slsa-vsa.json">
          <create-attestation-signature type="dsse" output-file-name="slsa-vsa.dsse.json" />
-       </create-verification-summary-file>
+      </create-verification-summary-file>
     </create-provenance-file>
   </zip-file>
 </artifact-configuration>
 ~~~
 
-#### Verification of SLSA verification summaries (VSA) {#slsa-vsa-verification}
+## Verification of SLSA verification summaries (VSA) {#slsa-vsa-verification}
 
 To verify a SLSA verification summary attestation (VSA), you need:
 
@@ -65,7 +60,7 @@ To verify a SLSA verification summary attestation (VSA), you need:
 > * `certificate-fingerprint`: The SHA-1 fingerprint of the X.509 publisher certificate.
 > * `subject`: The subject of the X.509 publisher certificate.
 
-To verify the verification summary attestation, the official [slsa-verifier](https://github.com/slsa-framework/slsa-verifier) tool can be used:
+To verify the verification summary attestation, the official [slsa-verifier](https://github.com/slsa-framework/slsa-verifier) tool can be used as follows.
 
 The following steps are required to verify a SLSA provenance attestation generated by SignPath: