From d606b8040e8d4995cdede8463d8cf784cecf7ba8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?V=C3=ADctor=20Cuadrado=20Juan?= <vcuadradojuan@suse.de>
Date: Tue, 5 Jul 2022 16:43:05 +0200
Subject: [PATCH] feat: Add new supported `v2/verify` payloads

---
 .../02-signature-verifier-policies.md         | 289 +++++++++++++++++-
 1 file changed, 285 insertions(+), 4 deletions(-)

diff --git a/docs/writing-policies/spec/host-capabilities/02-signature-verifier-policies.md b/docs/writing-policies/spec/host-capabilities/02-signature-verifier-policies.md
index f0e651bcdf..30f0a87557 100644
--- a/docs/writing-policies/spec/host-capabilities/02-signature-verifier-policies.md
+++ b/docs/writing-policies/spec/host-capabilities/02-signature-verifier-policies.md
@@ -79,7 +79,288 @@ UX, of course you can build on top of it or any of the other SDKs.
 In case you are implementing your own language SDK, these are the functions a
 policy that verifies signatures can use:
 
-| **waPC function name** | **Input payload**                                                                                                                                                                                                                                                                                                                                                                                                        | **Output payload**                                                                                                       |
-|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
-| `v1/verify`              | <code>{<br/>  // **mandatory**: image URI to verify<br/>  "image": string,<br/>  "pub_keys": [<br/>    // PEM-encoded public keys<br/>    string<br/>  ],<br/>  // optional:<br/>  "annotations": [<br/>    // signature annotations<br/>    {<br/>      "key": string,<br/>      "value": string<br/>    },<br/>  ]<br/>}</code>                                                                                                                           | <code>{<br/>   // true if image verified<br/>   "is_trusted": boolean,<br/>   // digest of verified image<br/>   "digest": string<br/>}</code> |
-| `v1/verify`              | <code>{<br/>  // **mandatory**: image URI to verify<br/>  "image": string,<br/>  "keyless": [<br/>    // list of (issuer, subject) tuples<br/>    {<br/>      // OIDC issuer<br/>      "issuer": string,<br/>      // signature subject (mail, CI URL, ...)<br/>      "subject": string<br/>    }<br/>  ],<br/>  // optional:<br/>  "annotations": [<br/>    // signature annotations<br/>    {<br/>      "key": string,<br/>      "value": string<br/>    },<br/>  ]<br/>}</code> | <code>{<br/>  // true if image verified<br/>  "is_trusted": boolean,<br/>  // digest of verified image<br/>  "digest": string<br/>}</code> |
+<table>
+<tr>
+<td> WaPC function name </td> <td> Input payload </td> <td> Output payload </td>
+</tr>
+<tr>
+<td>
+
+`v2/verify`
+
+</td>
+<td>
+
+```json
+{
+  type: "SigstorePubKeyVerify",
+
+  // **mandatory**: image URI to verify
+  "image": string,
+  "pub_keys": [
+    // PEM-encoded public keys
+    string
+    ],
+  // optional:
+  "annotations": [
+      // signature annotations
+      {
+        "key": string,
+        "value": string
+      },
+    ]
+}
+```
+
+</td>
+<td> 
+
+```json
+{
+   // true if image verified
+   "is_trusted": boolean,
+   // digest of verified image
+   "digest": string
+}
+```
+
+</td>
+</tr>
+<tr>
+<td>
+
+`v2/verify`
+
+</td>
+<td>
+
+```json
+{
+  type: "SigstoreKeylessVerify",
+
+  // mandatory: image URI to verify
+  "image": string,
+  "keyless": [
+    // list of (issuer, subject) tuples
+    {
+      // OIDC issuer
+      "issuer": string,
+      // signature subject (mail, CI URL, ...)
+      "subject": string
+    }
+  ],
+  // optional:
+  "annotations": [
+    // signature annotations
+    {
+      "key": string,
+      "value": string
+    },
+  ]
+}
+```
+
+</td>
+<td> 
+
+```json
+{
+   // true if image verified
+   "is_trusted": boolean,
+   // digest of verified image
+   "digest": string
+}
+```
+
+</td>
+</tr>
+<tr>
+<td>
+
+`v2/verify`
+
+</td>
+<td>
+
+```json
+{
+  type: "SigstoreKeylessPrefixVerify",
+
+  // mandatory: image URI to verify
+  "image": string,
+  "keyless_prefix": [
+    // list of (issuer, url_prefix) tuples
+    {
+      // OIDC issuer
+      "issuer": string,
+      // URL Prefix of subject (CI URL, ...)
+      "url_prefix": string
+    }
+  ],
+  // optional:
+  "annotations": [
+    // signature annotations
+    {
+      "key": string,
+      "value": string
+    },
+  ]
+}
+```
+
+</td>
+<td> 
+
+```json
+{
+   // true if image verified
+   "is_trusted": boolean,
+   // digest of verified image
+   "digest": string
+}
+```
+
+</td>
+</tr>
+
+<tr>
+<td>
+
+`v2/verify`
+
+</td>
+<td>
+
+```json
+{
+  type: "SigstoreGithubActionsVerify",
+
+  // mandatory: image URI to verify
+  "image": string,
+  // GitHub owner
+  "owner": string,
+  // optional:
+  // GitHub repository 
+  "repo": string
+  "annotations": [
+    // signature annotations
+    {
+      "key": string,
+      "value": string
+    },
+  ]
+}
+```
+
+</td>
+<td> 
+
+```json
+{
+   // true if image verified
+   "is_trusted": boolean,
+   // digest of verified image
+   "digest": string
+}
+```
+
+</td>
+</tr>
+</table>
+
+
+Marked for deprecation:
+
+<table>
+<tr>
+<td> WaPC function name </td> <td> Input payload </td> <td> Output payload </td>
+</tr>
+<tr>
+<td>
+
+`v1/verify`
+
+</td>
+<td>
+
+```json
+{
+  // **mandatory**: image URI to verify
+  "image": string,
+  "pub_keys": [
+    // PEM-encoded public keys
+    string
+    ],
+  // optional:
+  "annotations": [
+      // signature annotations
+      {
+        "key": string,
+        "value": string
+      },
+    ]
+}
+```
+
+</td>
+<td> 
+
+```json
+{
+   // true if image verified
+   "is_trusted": boolean,
+   // digest of verified image
+   "digest": string
+}
+```
+
+</td>
+</tr>
+<tr>
+<td>
+
+`v1/verify`
+
+</td>
+<td>
+
+```json
+{
+  // mandatory: image URI to verify
+  "image": string,
+  "keyless": [
+    // list of (issuer, subject) tuples
+    {
+      // OIDC issuer
+      "issuer": string,
+      // signature subject (mail, CI URL, ...)
+      "subject": string
+    }
+  ],
+  // optional:
+  "annotations": [
+    // signature annotations
+    {
+      "key": string,
+      "value": string
+    },
+  ]
+}
+```
+
+</td>
+<td> 
+
+```json
+{
+   // true if image verified
+   "is_trusted": boolean,
+   // digest of verified image
+   "digest": string
+}
+```
+
+</td>
+</tr>
+
+</table>