Add keyspec for notional identity intermediate & docs to create it.

Author: flihp

data/platform-identity-intermediate.keyspec.json

@@ -0,0 +1,12 @@
+{
+    "common_name": "Platform Identity Intermediate PVT1",
+    "id":14,
+    "algorithm":"Ecp384",
+    "capabilities":"All",
+    "domain":"DOM1",
+    "hash":"Sha384",
+    "label":"platform-identity-intermediate-pvt1",
+    "purpose":"Identity",
+    "initial_serial_number":"0000000000000000000000000000000000000000",
+    "self_signed":false
+}

docs/intermediate.md

@@ -0,0 +1,41 @@
+# YubiHSM Provisioning Guide for PVT1 Programming
+
+Perform the following steps to provision a YubiHSM for PVT1 programming.
+It's worth noting that the `offline-keystore` tool was designed for a specific purpose and this ain't it.
+It does however have all of the functionality we require, we just have to pass in additional options to override defaults that don't make sense when setting up an intermediate.
+
+1. Reset your YubiHSM. There are a number of ways to do this:
+    1. Follow the instructions from YubiCo to either reset the device with a physical mechanism as is required if you don’t know your password, or using the yubihsm-shel if you do: https://developers.yubico.com/YubiHSM2/Usage_Guides/Factory_reset.html
+    1. The `offline-keystore` repo has a simple tool that can reset your password with fewer key presses than the `yubihsm-shell`. From the root of a `offline-keystore` git checkout: `cargo run --bin yhsm -- --auth-id X reset`. The `auth-id` option is used to pass in the object id of the auth credential. By default this is ‘1’ however the `oks` tool uses auth id ‘2’ instead.
+1. Checkout the `offline-keystore` repo: https://github.com/oxidecomputer/offline-keystore
+1. Initialize the YubiHSM:
+    ``` sh
+    $ cargo run --bin oks -- hsm --no-backup initialize --passwd-challenge
+    ```
+    NOTE: `--no-backup` disables the wrap key creation and splitting we do for the offline roots
+    NOTE: `--passwd-challenge` disables the passwd mgmt flows we do for the offline roots & will challenge you for a password on the console. Pick a strong password, preferably one generated by a password manager and stored in same.
+1. Generate the identity signing key:
+    ```sh
+    $ cargo run --bin oks -- \
+	    hsm --no-backup \
+        generate \
+	    --key-spec data/platform-identity-intermediate.keyspec.json
+    ```
+    NOTE: the keyspec file is checked into the `offline-keystore` repo
+1. Generate the directory structure and config file for the openssl CA:
+    ```sh
+    $ cargo run --bin oks -- \
+        ca initialize \
+        --key-spec data/platform-identity-intermediate.keyspec.json
+    ```
+
+## What happened?
+
+At the end of all of this the HSM has:
+1. created an auth credential w/ a password set by the caller
+1. extracted the certificate for the attestation key on the YubiHSM: `output/hsm.attest.cert.pem`
+1. deleted the default auth credential created when the device was reset
+1. created a signing key per the provided keyspec, this will be the key used by our intermediate CA for signing certs
+1. collected an attestation by the YubiHSM proving the key created was created on this specific YubiHSM: `output/platform-identity-intermediate-pvt1.attest.cert.pem`
+1. created a directory structure and config as required by the `openssl ca` command using the YubiHSM as a signing back-end: `ca-state/platform-identity-intermediate-pvt1`
+1. created a CSR for the signing key such that it can be certified and included into an existing PKI: `output/platform-identity-intermediate-pvt1.csr.pem`