.. hsm2-tools-setup.rst .. _hsm2-tools-setup-label: YubiHSM 2 Setup Tool ===================== .. Note:: The YubiHSM Setup is deprecated. Please use :ref:`hsm2-tools-manager-label` instead. The SDK ships with a tool called `yubihsm-setup `_ that helps with setting up a device for specific use cases. The tool assumes familiarity with the key concepts of YubiHSM such as :ref:`hsm2-concepts-domain-label`, :ref:`hsm2-concepts-capability-label` and :ref:`hsm2-concepts-objectid-label`. It currently supports the following: * setup for KSP/ADCS and EJBCA; * restoring a previous configuration * resetting the device to factory defaults * exporting all existing objects The tool is based around the concept of secret-sharing. When setting up Objects, those are exported with a freshly created Wrap Key. The key is never stored on disk, but rather it is printed on the screen as shares. The key concepts here are: * The number of shares, which is the number of parts the key should be divided into. * The security threshold, which is the minimum number of shares required to reconstruct the Wrap Key. Besides splitting the Wrap Key into shares, the tool (by default) also exports under wrap all the newly created objects and saves them in the current directory. This can be used at a later time to “clone” or recover a device. This operation can be performed either with ``yubihsm-setup`` or manually if the Wrap Key is known. By default, the Authentication Key used to establish a Session with the device is also normally deleted at the end of the process. Default behavior can be altered with command line options. For more information, consult the tool's help. Setup for EJBCA ---------------- When setting up the device for use by EJBCA, the setup tool also generates an asymmetric key pair and an X509 certificate suitable for use as a CA key. The setup tool can be re-run as many times as the number of asymmetric keys to be generated since each run will produce only one key pair and one corresponding X509 certificate. .. Note:: Using the ``--no-new-authkey`` flag prevents generation of a new Wrap Key and a new Authentication Key. How It Works ------------- For the JAVA implementation, a key pair can be used to perform PKCS#11 operations only if the key and its corresponding X509 certificate are stored under the same ID on the device (the value of their CKA_ID attributes is the same). To store them under the same ID, run the YubiHSM 2 Setup tool with the ``ejbca`` subcommand: 1. Generate an Asymmetric Key on the YubiHSM 2. 2. Generate an attestation certificate for the asymmetric key and import it into the YubiHSM 2 under the same ID as the Asymmetric Key. The attestation certificate stored on the YubiHSM 2 is, in fact, only a placeholder certificate for the public key. It is never used by EJBCA because EJBCA stores the CAs' certificates in a dedicated database.