[otbn] Document key sideload

Fixes #8502 Signed-off-by: Philipp Wagner <phw@lowrisc.org>
lowRISC · Oct 13, 2021 · e9f0450 · e9f0450
1 parent 2428d66
commit e9f0450
Show file tree

Hide file tree

Showing 2 changed files with 61 additions and 0 deletions.
diff --git a/hw/ip/otbn/data/otbn.hjson b/hw/ip/otbn/data/otbn.hjson
@@ -318,6 +318,11 @@
           resval: 0,
           desc: "A `LOOP` error was observed."
         }
+        { bits: "5",
+          name: "key_invalid"
+          resval: 0,
+          desc: "A `KEY_INVALID` error was observed."
+        }
 
         // Fatal errors. Keep in sync with list in FATAL_ALERT_CAUSE.
         { bits: "16",

diff --git a/hw/ip/otbn/doc/_index.md b/hw/ip/otbn/doc/_index.md
@@ -374,6 +374,46 @@ Reads never stall.
         The accumulator register used by the {{< otbnInsnRef "BN.MULQACC" >}} instruction.
       </td>
     </tr>
+    <tr>
+      <td>0x4</td>
+      <td>RO</td>
+      <td>KEY_S0_L</td>
+      <td>
+Bits [255:0] of share 0 of the 384b OTBN sideload key provided by the [Key Manager]({{< relref "/hw/ip/keymgr/doc" >}}).
+
+A `KEY_INVALID` software error is raised if the Key Manager does not provide a valid key.
+      </td>
+    </tr>
+    <tr>
+      <td>0x5</td>
+      <td>RO</td>
+      <td>KEY_S0_H</td>
+      <td>
+Bits [383:256] of share 0 of the 384b OTBN sideload key provided by the [Key Manager]({{< relref "/hw/ip/keymgr/doc" >}}).
+
+A `KEY_INVALID` software error is raised if the Key Manager does not provide a valid key.
+      </td>
+    </tr>
+    <tr>
+      <td>0x6</td>
+      <td>RO</td>
+      <td>KEY_S1_L</td>
+      <td>
+Bits [255:0] of share 1 of the 384b OTBN sideload key provided by the [Key Manager]({{< relref "/hw/ip/keymgr/doc" >}}).
+
+A `KEY_INVALID` software error is raised if the Key Manager does not provide a valid key.
+      </td>
+    </tr>
+    <tr>
+      <td>0x7</td>
+      <td>RO</td>
+      <td>KEY_S1_H</td>
+      <td>
+Bits [383:256] of share 1 of the 384b OTBN sideload key provided by the [Key Manager]({{< relref "/hw/ip/keymgr/doc" >}}).
+
+A `KEY_INVALID` software error is raised if the Key Manager does not provide a valid key.
+      </td>
+    </tr>
   </tbody>
 </table>
 
@@ -449,6 +489,15 @@ Refer to the [Secure Wipe]({{<relref "#design-details-secure-wipe">}}) section f
 
 In order to detect and mitigate fault injection attacks on the OTBN, the host CPU can read the number of executed instructions from {{< regref "INSN_CNT">}} and verify whether it matches the expectation.
 
+## Key Sideloading
+
+OTBN software can make use of a single 384b wide key provided by the [Key Manager]({{<relref "/hw/ip/keymgr/doc" >}}), which is made available in two shares.
+The key is passed through a dedicated connection between the Key Manager and OTBN to avoid exposing it to other components.
+Software can access the first share of the key through the [`KEY_S0_L` and `KEY_S0_H` WSRs](#wsrs), and the second share of the key through the [`KEY_S1_L` and `KEY_S1_H` WSRs](#wsrs).
+
+It is up to host software to configure the Key Manager so that it provides the right key to OTBN at the start of the operation, and to remove the key again once the operation on OTBN has completed.
+A `KEY_INVALID` software error is raised if the Key Manager does not present a valid key when OTBN software accesses any of the `KEY_*` WSRs.
+
 # Theory of Operations
 
 ## Block Diagram
@@ -673,6 +722,13 @@ This way, no alert is generated without setting an error code somewhere.
         A loop stack-related error was detected.
       </td>
     </tr>
+    <tr>
+      <td><code>KEY_INVALID<code></td>
+      <td>software</td>
+      <td>
+        An attempt to read a `KEY_*` WSR was detected, but no valid key was provided by the key manager.
+      </td>
+    </tr>
     <tr>
       <td><code>IMEM_INTG_VIOLATION<code></td>
       <td>fatal</td>