.. hsm2-openssl-windows-guide.rst .. _hsm2-openssl-windows-guide-label: =============================== YubiHSM and OpenSSL on Windows =============================== This section covers setup, configuration, and usage of the Yubico YubiHSM2 with OpenSSL on Windows 10 Overview ========= The Windows OS does not come with many utilities and support found on Linux. This covers installation and usage on a bare Windows 10 system. Aside from the bare OS, Visual Studio 2019 (v16.2) was installed. For this example, all of the binaries are 64 bit. 1. Download the YubiHSM2 development kit. 2. Download the ``libp11`` source. 3. Download the OpenSC installer. 4. Download the Shining Light Productions OpenSSL installer. Installation ============== YubiHSM2 Development Kit ------------------------- :Step 1: Unzip the downloaded file to install the development kit. The development kit has utilities and a couple of MSI files. :Step 2: Install the files (connector and CSG provider) to connect to the YubiHSM2. You should now be able to use the ``yubi-shell.exe`` to connect to the YubiHSM2. :Step 3: Create the YubiHSM2 connector configuration file. Then set the ``YUBIHSM_PKCS11_CONF`` environmental variable with its path and name. See below for example. .. code-block:: bash Yubihsm_pkcs11.cnf connector = http://127.0.0.1:12345 OpenSC and OpenSSL Distributions --------------------------------- The Shining Light Productions OpenSSL distribution is not an official distribution, it is provided by volunteers. Throw them a donation! The OpenSC and OpenSSL distributions will be installed under ``C:\Program Files``. After OpenSC is installed, you should be able to access the YubiHSM2 ``usingpkcs11-tool``. .. code-block:: bash C:\PROGRA~1\OpenSC Project\OpenSC\tools>set YUBIHSM_PKCS11_CONF=C:\Users\your_name \yubihsm2-sdk-2019-03-win64-amd64 \yubihsm2-sdk\yubihsm_pkcs11.cnf C:\PROGRA~1\OpenSC Project\OpenSC\tools>pkcs11-tool --module C:\Users\your_name\yubihsm2-sdk-2019-03-win64-amd64\yubihsm2-sdk\bin \yubihsm_pkcs11.dll --login --pin 0001password -I Cryptoki version 2.40 Manufacturer Yubico (www.yubico.com) Library YubiHSM PKCS#11 Library (ver 2.1) Using slot 0 with a present token (0x0) C:\PROGRA~1\OpenSC Project\OpenSC\tools> libp11 Source -------------- Download the ``libp11`` source from GitHub. This will need to be compiled. :Step 1: Open a Visual Studio x64 Native Tools command prompt. :Step 2: Go to the source directory. :Step 3: Type: ``nmake -f Makefile.mak OPENSSL_DIR=\progra~1\OPENSS~1 BUILD_FOR=WIN64`` The ``.dll`` files will be in the source directory. Configuration -------------- :Step 1: Two environmental variables must be set: ``YUBIHSM_PKCS11_CONF`` and ``OPENSSL_CONF``. These must be set to the location and file name of the respective configuration files. The OpenSSL configuration file is configured with the engine configuration at the top. The HSM PIN, which is its password, may be set in this file. The password here is the YubiHSM2 default password for the default ``administratoruser``. .. code-block:: bash yubi_openssl.cnf openssl_conf = openssl_init [ openssl_init ] engines = engines_section [ engines_section ] pkcs11 = pkcs11_section [ pkcs11_section ] engine_id = pkcs11 dynamic_path = C:\\Users\\your_name\\Documents\\sourceproj\\ libp11-master\\src pkcs11.dll MODULE_PATH = C:\\Users\\your_name\\yubihsm2-sdk- 2019-03-win64-amd64\\yubihsm2-sdk\\bin yubihsm_pkcs11.dll PIN = 0001password init = 0 :Step 2: To run the OpenSSL tool commands, the rest of the file contains the normal configuration sections. OpenSSL v1.1.1c requires more configuration than v1.0.2, which is on Ubuntu. The following sections are for creating a self-signed certificate authority certificate. This is just for demonstration, and not to be placed on the FCT stations. .. code-block:: bash More yubi_openssl.cnf [ req ] prompt = no distinguished_name = req_distinguished_name default_bits = 4096 string_mask = utf8only default_md = sha256 x509_extensions = v3_ca_ext [ req_distinguished_name ] countryName = US stateOrProvinceName = Washington localityName = Seattle organizationName = Banana Inc. organizationalUnitName = Fruit Bunch commonName = Root Test Cert [ v3_ca_ext ] subjectKeyIdentifier = hash authorityKeyIdentifier = keyid:always,issuer basicConstraints = critical, CA:true keyUsage = critical, digitalSignature, cRLSign, keyCertSign certificatePolicies = 2.5.29.32, @policysection [ policysection ] policyIdentifier = 1.3.5.8 userNotice.1 = @notice [ notice ] explicitText = "Yubi Demo Banana Inc. Development Certificate" :Step 3: At this point, you should be able to create a self-signed certificate. In this example, key ID 0:0064 is the identifier for a 4096-bit RSA key. .. code-block:: bash C:\Users\your_name>openssl req -new -x509 -days 365 -sha256 -engine pkcs11 -keyform engine -key 0:0064 -out cert.pem engine "pkcs11" set. C:\Users\your_name>dir cert.pem Volume in drive C is OSDisk Volume Serial Number is AC07-5227 Directory of C:\Users\your_name 08/22/2019 02:20 PM 2,322 cert.pem 1 File(s) 2,322 bytes 0 Dir(s) 179,197,755,392 bytes free C:\Users\your_name>openssl x509 -noout -text -in cert.pem Certificate: Data: Version: 3 (0x2) Serial Number: 2d:71:6a:fd:8b:ab:5a:b8:3e:5c:cc:c0:bc:b1:a5:11:df:7f:2b:1d Signature Algorithm: sha256WithRSAEncryption Issuer: C = US, ST = Washington, L = Seattle, O = Banana Inc., OU = Fruit Bunch, CN = Root Test Cert Validity Not Before: Aug 22 21:20:07 2019 GMT Not After : Aug 21 21:20:07 2020 GMT Subject: C = US, ST = Washington, L = Seattle, O = Banana Inc., OU = Fruit Bunch, CN = Root Test Cert Subject Public Key Info: Public Key Algorithm: rsaEncryption RSA Public-Key: (4096 bit) Modulus: 00:bd:0c:71:1a:4b:19:86:17:d0:d1:bf:c7:27:83: