.. hsm2-initial-provision-deploy-guide.rst

.. _hsm2-initial-provision-deploy-guide-label:

==========================================
Initial Provisioning and Deployment Guide
==========================================

This topic covers operations pertaining to the initial provisioning and deployment of YubiHSM 2 devices.

Familiarity with the device, its features and capabilities is assumed.


.. Important::
   The YubiHSM 2 ships with a default Authentication Key with a well-known password. It is imperative that it is removed (single use case) or changed prior to production deployment.


Known Usage Cases
==================

When only a single application needs to be provisioned, Yubico recommends that all Authentication Keys and material be provisioned only with Capabilities specific to that use case.

.. Note::
   This type of deployment requires devices to be physically reset and re-provisioned (single use case) or changed should a new use case arise.

HMAC
======


:Step 1: Establish a session with the default Authentication Key.

    .. code-block:: bash

      yubihsm> connect
               Session keepalive set up to run every 15 seconds
      yubihsm> session open 1 password
               Created session 0

:Step 2: Create an Authentication Key for Auditing.

   .. code-block:: bash

      yubihsm> put authkey 0 0 "Audit auth key" all get-log-entries none
               $AUDIT_PASS
               Stored Authentication key 0xd054

:Step 3:  Create a Wrap Key for importing application Authentication Keys and secrets.

   .. code-block:: bash

      yubihsm> get random 0 16
               5b61e89468cc8f2a274715c78c3d4753
      yubihsm> put wrapkey 0 0 "HMAC wrap Key" all import-wrapped
               sign-hmac:verify-hmac 5b61e89468cc8f2a274715c78c3d4753
               Stored Wrap key 0xf09a

:Step 4:  Create an Authentication Key for use with the above Wrap Key.

   .. code-block:: bash

      yubihsm> put authkey 0 0 "Provisioning HMAC wrap auth key" all
               import-wrapped none $WRAP_PASS
               Stored Authentication key 0xf10f

:Step 5:  Delete the default Authentication Key.

   .. code-block:: bash

      yubihsm> delete 0 1 authentication-key

:Step 6:  Create a wrapped Authentication Key and HMAC Key for the application.

   .. code-block:: bash

      echo -ne '\x5b\x61\xe8\x94\x68\xcc\x8f\x2a\x27\x47\x15\xc7\x8c\x3d
          \x47\x53' > wrap.key
      echo $HMAC_PASS | yubihsm-wrap -a aes128-yubico-authentication
         -c sign-hmac,verify-hmac -d 1 -l "HMAC auth key" -k wrap.key --in
         --out auth.out -e none
      echo -ne '\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b
         \x0b\x0b\x0b\x0b\x0b\x0b\x0b' > hmac.key
      yubihsm-wrap -a hmac-sha256 -c sign-hmac,verify-hmac -d 1 -l "HMAC key"
          -k wrap.key --in hmac.key --out hmac.out

:Step 7: Open a Session with the wrap Authentication Key.

   .. code-block:: bash

      yubihsm> session open 0xf10f $WRAP_PASS
               Created session 1

:Step 8:  Import the two wrapped keys in the new Session.

   .. code-block:: bash

       yubihsm> put wrapped 1 0xf09a auth.out
                Object imported as 0x2a74 of type authentication-key
       yubihsm> put wrapped 1 0xf09a hmac.out
                Object imported as 0xd1a2 of type hmac-key

:Step 9:  Open a session with the new application Authentication Key.

    .. code-block:: bash

       yubihsm> session open 0x2a74 $HMAC_PASS
                Created session 2

:Step 10:  Run HMAC-SHA256 Test vector #1 and get expected output.

   .. code-block:: bash

      yubihsm> hmac 2 0xd1a2b0344c61d8db38535ca8afceaf0bf12b881dc200c9833
               da726e9376c2e32cff7
      echo -ne '\x48\x69\x20\x54\x68\x65\x72\x65' | openssl dgst -hex -mac
          hmac -macopt hexkey:0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b
          -sha256 (stdin)= b0344c61d8db38535ca8afceaf0bf12b881dc200c
          9833da726e9376c2e32cff7

PKCS11 / RSA
==============

This example assumes that only RSA operations will be performed and that RSA keys will be generated on device over PKCS#11. For using the :ref:`hsm2-pkcs11-guide-label` a ``yubihsm\_pkcs11.conf`` file needs to exist and point at the desired connector.

:Step 1:  Establish a Session with the default Authentication Key.

   .. code-block:: bash

      yubihsm> connect
               Session keepalive set up to run every 15 seconds
      yubihsm> session open 1 password
               Created session 0

:Step 2:  Create an Authentication Key for Auditing.

   .. code-block:: bash

      yubihsm> put authkey 0 0 "Audit auth key" all audit none $AUDIT_PASS
               Stored Authentication key 0xd054

:Step 3:  Optionally enable forced audits.

   .. code-block:: bash

      yubihsm> put option 0 force-audit 01

:Step 4:  Create an Authentication Key for usage with the PKCS11 module.

   .. code-block:: bash

      yubihsm> put authkey 0 0 "PKCS11 RSA" 1 delete-asymmetric-key:
               generate-asymmetric-key:sign-pkcs:sign-pss sign-pkcs:sign-pss
               $PKCS11_PASS
               Stored Authentication key 0xf10f

:Step 5:  Delete the default Authentication Key.

   .. code-block:: bash

      yubihsm> delete 0 1 authentication-key

:Step 6:  Use pkcs11-tool to generate an RSA key.

   .. code-block:: bash

      pkcs11-tool --module /path/to/yubihsm_pkcs11.so -l --pin
           f10f${PKCS11_PASS} -k --key-type rsa:2048 --usage-sign
           --label "RSA key"
      Using slot 0 with a present token (0x0)
      Key pair generated:
      Private Key Object; RSA
        label:      RSA key
        ID:         e77d
        Usage:      sign
      Public Key Object; RSA 2048 bits
        label:      RSA key
        ID:         e77d
        Usage:      none