Merge pull request #565 from bkanui/bk-hsm2-oldbook

Archive old YubiHSM2 documentation

content/Archive_Old_Dev_Docs/README.md

@@ -0,0 +1,28 @@
+# Old documentation
+
+This folder contains documentation that has been removed or moved from dev.yubico.com to docs.yubico.com.
+
+These docs have been preserved here in case a customer requests an old manual or doc site contributors need to reference past material.
+
+The docs in this folder are organized by product. The content files represent the most recent state of the content prior to removal.
+
+## Removed books
+
+The following table lists documentation that have been replaced/moved from dev.yubico.com to docs.yubico.com and preserved in this folder.
+
+| Book Title | Book Slug | books.yaml Filepath | old-docs filepath | Old URL | Redirect | Reason for Removal | Removal Date |
+|------------|-----------|---------------------|-------------------|---------|----------|--------------------|--------------|
+| YubiHSM2 | YubiHSM2 | content/YubiHMS2 | developers.yubico.com/content/YubiHMS2 | https://developers.yubico.com/YubiHSM2/ | https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/index.html | Content absorbed into combined YubiHSM 2 User Guide | 9/25/2023 |
+
+
+## View an old book's PDF output
+
+To view an old book's PDF output, open the folder containing the book of interest, then go to **pdf-output** -> **webdocs.pdf**. HTML output is not preserved due to the number of files involved and resulting increase in the size of the repository.
+
+## Building an old book locally
+
+If you would like to build the docs locally (HTML and/or PDF previews), do so just as you would for current books (e.g. ``make autobuild_web``). All of the book's files and folders (config file, Makefile, index file, etc) are included.
+
+However, if the doc system is updated in the future, those updates may require changes to books' config files, Makefiles, folder structures, etc. Old books may not be updated to comply with such changes, which may result in errors when trying to build the docs with the current toolset.
+
+Some of the files are in asciidoc (.adoc) format, the make autobuild steps for building HTML or PDF do not apply. 

content/Archive_Old_Dev_Docs/YubiHSM2/.conf.json

@@ -0,0 +1,21 @@
+{
+  "order": [
+    "Releases",
+    "Product_Overview",
+    "Concepts",
+    "Commands",
+    "Component_Reference",
+    "Usage_Guides",
+    "Backup_and_Recovery"
+  ],
+  "suggest-edits": {},
+  "git": [
+    {
+      "url": "[email protected]:Yubico/yubico-binaries.git",
+      "preserve_mtimes": true,
+      "files": [
+        ["yubihsm2/releases/*", "Releases/"]
+      ]
+    }
+  ]
+}

content/Archive_Old_Dev_Docs/YubiHSM2/Backup_and_Restore/index.adoc

@@ -0,0 +1,129 @@
+== Backup and Restore
+
+=== Introduction
+
+The YubiHSM 2 supports encrypted export and import of objects using a symmetric AES-CCM based scheme.
+
+The examples below assume the default authentication key (0x0001). If you use some other authentication key make sure that it has the capability `put-wrap-key` and has the correct delegated capabilities,
+otherwise you will get a "wrong permissions for operation" error.
+
+=== Backup Using YubiHSM Shell
+
+Make sure you have a Wrap Key with the Capabilities `export-wrapped`, `import-wrapped` and applicable Delegated Capabilities set:
+
+[source, bash]
+----
+$ yubihsm-shell -a get-pseudo-random --count=32 --out=wrap.key
+...
+$ yubihsm-shell -a put-wrap-key --capabilities export-wrapped,import-wrapped --delegated=sign-pkcs,decrypt-pkcs,exportable-under-wrap --in=wrap.key
+...
+Stored Wrap key 0xd581
+----
+
+When this Wrap Key is present, any Object in the same Domain and with the Capability `exportable-under-wrap` and Capabilities matching the Wrap Key's Delegated Capabilities can be exported:
+
+[source, bash]
+----
+$ yubihsm-shell -a generate-asymmetric-key -A rsa2048 --capabilities exportable-under-wrap,sign-pkcs,decrypt-pkcs
+...
+Generated Asymmetric key 0x6e77
+$ yubihsm-shell -a get-wrapped --wrap-id=0xd581 --object-id=0x6e77 -t asymmetric-key --out=key_6e77.yhw
+...
+----
+
+You now have an encrypted backup of the Asymmetric Key `0x6e77` in the file key_6e77.yhw. *The file wrap.key here contains the cleartext version of the Wrap Key loaded into your YubiHSM and should be considered sensitive*.
+
+=== Backup Using YubiHSM Setup
+
+The tool `yubihsm-setup` can be used to backup all exportable objects at once:
+
+[source, bash]
+----
+$ yubihsm-setup dump
+Enter the wrapping key ID to use for exporting objects: 0xd581
+...
+Successfully exported object Asymmetric with ID 0x6e77 to ./0x6e77.yhw
+All done
+----
+
+=== Restore Using YubiHSM Shell
+
+Considering a fresh device where you want to restore the previously backed up key `0x6e77`
+
+[source, bash]
+----
+$ yubihsm-shell -a put-wrap-key -A aes256-ccm-wrap -c export-wrapped,import-wrapped --delegated=sign-pkcs,decrypt-pkcs,exportable-under-wrap --in=wrap.key -i 0xd581
+...
+Stored Wrap key 0xd581
+$ yubihsm-shell -a put-wrapped --wrap-id=0xd581 --in=key_6e77.yhw
+...
+Object imported as 0x6e77 of type asymmetric-key
+----
+
+== Backup and Restore of Keys Managed via YubiHSM Key Storage Provider
+
+ADCS does not set the `NCRYPT_ALLOW_EXPORT_FLAG` when generating a key neither through the setup UI, nor the `Install-ADCSCertificationAuthority` PowerShell module.  When creating an ADCS root CA key via the YubiHSM 2, we add the `exportable-under-wrap` Capability by default, so that backup and restore functionality is available through the following manual process:
+
+=== Identify Your Private Key Container Name
+
+Open an elevated command prompt/shell.
+
+Use the certutil command:
+
+[source, powershell]
+----
+PS1> certutil -store My
+----
+
+to view the currently installed certificates in the Local Machine "My" store.
+
+Find the target certificate in the list.
+
+Find the `Key Container` property of the target certificate. The Provider property should be equal to `YubiHSM Key Storage Provider`.
+
+Record the `Cert Hash` property to identify the certificate.
+
+=== Backup the Target Certificate
+
+Using any available means (certmgr.msc, PowerShell, certutil), export the target certificate, but without the private key in DER format. The YubiHSM does not provide a mechanism for returning the raw private key to Windows, so generating a PKCS#12 container is not currently possible. For example:
+
+[source, powershell]
+----
+PS1> certutil -split -store My <Cert Hash>
+----
+
+will export the certificate in .crt format to a file named `<Cert Hash>.crt`.
+
+=== Backup the Target Private Key
+
+Using the instructions for exporting a private key under wrap via `yubihsm-shell` (see above), export the target private key with the `label` property equal to the `Key Container` property.
+The Authentication Key that performs this operation must have the `export-wrapped` capability set.
+
+=== Restore the Target Private Key
+
+Using the instructions for importing a private key under wrap via `yubihsm-shell` (see above), import the target private key file to your backup YubiHSM. The Authentication Key that performs this operation must have the `import-wrapped` capability set.
+
+The imported key object should have the same Label property as the original object.
+
+=== Restore the Target Certificate
+
+Move the target certificate file generated above to the target machine.
+
+Import the certificate to the LocalMachine "My" store via your favorite method. At this point, the certificate will not have an associated private key.  Use the `-repairstore` functionality of `certutil` to re-associate the certificate to the private key.
+Make sure that the target private key is visible via the YubiHSM KSP, using
+
+[source, powershell]
+----
+PS1> certutil -key -csp "YubiHSM Key Storage Provider"
+----
+
+This command will list all private keys (and their corresponding container names -- which are equal to the Label property in the YubiHSM visible to the current Authentication Key).
+
+Open an elevated prompt and execute the command:
+
+[source, powershell]
+----
+PS1> certutil -repairstore MY <Cert Hash>
+----
+
+Repeat the steps under Identify Your Private Key Container Name to verify that the certificate has been associated with the YubiHSM Key Storage Provider and has the correct `Key Container` property value.

content/Archive_Old_Dev_Docs/YubiHSM2/Commands/Authenticate_Session.adoc

@@ -0,0 +1,46 @@
+== AUTHENTICATE SESSION
+
+Complete the mutual authentication process started with
+link:Create_Session.adoc[Create Session].
+
+== Description
+
+Finish the Session negotiation and authenticate the Session to the device.
+After this command completes successfully the Session is authenticated and
+can be used.
+
+== Shell Example
+
+Create a new Session with Authentication Key `1` using the password `password`, this performs
+both the creation and authentication steps:
+
+  yubihsm> session open 1 password
+  Created session 0
+
+== Protocol Details
+
+=== Command
+
+|==================
+|T~c~ = 0x04
+|L~c~ = 17
+|V~c~ = S \|\| B \|\| M
+|==================
+
+S := Session ID (1 byte)
+
+B := Host Cryptogram (8 bytes)
+
+M := CMAC(S-MAC, 0^16^ || T || L~c~ + 8 || S || B) (8 bytes)
+
+This is the first authenticated message in the chain.
+
+The device verifies `M` and `B`, both using `S-MAC`.
+
+=== Response
+
+|===========
+|T~r~ = 0x84
+|L~r~ = 0
+|V~r~ = Ø
+|===========

content/Archive_Old_Dev_Docs/YubiHSM2/Commands/Blink_Device.adoc

@@ -0,0 +1,33 @@
+== BLINK DEVICE
+
+Blink the device.
+
+== Description
+
+Blink the LED of the device to identify it.
+
+== Shell Example
+
+Blink the device for 15 seconds:
+
+  yubihsm> blink 0 15
+
+== Protocol Details
+
+=== Command
+
+|===========
+|T~c~ = 0x6b
+|L~c~ = 1
+|V~c~ = S
+|===========
+
+S := Seconds to blink for (1 byte)
+
+=== Response
+
+|===========
+|T~r~ = 0xeb
+|L~r~ = 0
+|V~r~ = Ø
+|===========

content/Archive_Old_Dev_Docs/YubiHSM2/Commands/Change_Authentication_Key.adoc

@@ -0,0 +1,46 @@
+== CHANGE AUTHENTICATION KEY
+
+Change an Authentication Key.
+
+== Description
+
+Replace the Authentication Key used to establish the current Session. It is not possible to modify any of the metadata connected to the Object such as Domains or Capabilities. Only the payload data of the Object (i.e., the long-lived symmetric keys) will be modified.
+
+The same `PBKDF2` derivation scheme described in link:../Concepts/Session.adoc[Session] is available.
+
+== Shell Example
+
+Change the current Authentication Key deriving it from the password `newpassword`:
+
+  yubihsm> change authkey 0 1 newpassword
+  Changed Authentication key 0x0001
+
+== Protocol Details
+
+=== Command
+
+|=======================
+|T~c~ = 0x6c
+|L~c~ = 2 + 1 + 16 + 16
+|V~c~ = I \|\| A \|\| K~e~ \|\| K~m~
+|=======================
+
+Replace the currently used Authentication Key with a new set of keys.
+
+I := link:../Concepts/Object_ID.adoc[Object ID] of the Authentication Key (2 bytes)
+
+A := link:../Concepts/Algorithms.adoc[Algorithm] (1 byte)
+
+K~e~ := Encryption Key (16 bytes)
+
+K~m~ := Mac Key (16 bytes)
+
+=== Response
+
+|===========
+|T~r~ = 0xec
+|L~r~ = 2
+|V~r~ = I
+|===========
+
+I := link:../Concepts/Object_ID.adoc[Object ID] of the changed Object (2 bytes)

content/Archive_Old_Dev_Docs/YubiHSM2/Commands/Close_Session.adoc

@@ -0,0 +1,31 @@
+== CLOSE SESSION
+
+Close session.
+
+== Description
+
+Close the current link:../Concepts/Session.adoc[Session] and release it for re-use.
+
+== Shell Example
+
+Close Session 0:
+
+  yubihsm> session close 0
+
+== Protocol Details
+
+=== Command
+
+|===========
+|T~c~ = 0x40
+|L~c~ = 0
+|V~c~ = Ø
+|===========
+
+=== Response
+
+|===========
+|T~r~ = 0xc0
+|L~r~ = 0
+|V~r~ = Ø
+|===========

content/Archive_Old_Dev_Docs/YubiHSM2/Commands/Create_Otp_Aead.adoc

@@ -0,0 +1,41 @@
+== CREATE OTP AEAD
+
+Create a Yubico OTP AEAD.
+
+== Description
+
+Create a Yubico OTP AEAD using the provided data.
+
+== Shell Example
+
+Create a new AEAD using Otp-aead Key `0x027c` with the key
+`000102030405060708090a0b0c0d0e0f` and private ID `010203040506`. Store the result
+in the file `aead`:
+
+  yubihsm> otp aead_create 0 0x027c 000102030405060708090a0b0c0d0e0f 010203040506 aead
+
+== Protocol Details
+
+=== Command
+
+|===============
+|T~c~ = 0x61
+|L~c~ = 24
+|V~c~ = I \|\| K \|\| P
+|===============
+
+I := link:../Concepts/Object_ID.adoc[Object ID] of the OTP AEAD Key (2 bytes)
+
+K := OTP Key (16 bytes)
+
+P := OTP Private ID (6 bytes)
+
+==== Response
+
+|===========
+|T~r~ = 0xe1
+|L~r~ = L~A~
+|V~r~ = A
+|===========
+
+A := Nonce concatenated with AEAD (36 bytes)