Introduction
What is YubiHSM 2?
The YubiHSM 2 is a Hardware Security Module (HSM) that is cost-effective for all organizations. It provides advanced cryptography including hashing, asymmetric, and symmetric key cryptography to protect the cryptographic keys that secure critical applications, identities, and sensitive data in an enterprise for certificate authorities, databases, code signing and more.
Important
The FIPS certification of the YubiHSM 2 [FIPS 140-2 Level 3] is recorded on the website of the National Institute of Standards and Technology at https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/3916.
System Requirements
The YubiHSM 2 SDK is built and provided for the following operating systems.
| Operating System | Version | Architecture |
|---|---|---|
| CentOS | 7 | amd64 |
| CentOS | 8 | amd64 |
| Debian | 9 Stretch (stable) | amd64 |
| Debian | 10 Buster | amd64 |
| Debian | 11 Bullseye | amd64 |
| Fedora | 33 | amd64 |
| Fedora | 34 | amd64 |
| Ubuntu | 14.04 Trusty Tahr | amd64 |
| Ubuntu | 16.04 Xenial Xerus | amd64 |
| Ubuntu | 18.04 Bionic Beaver | amd64 |
| Ubuntu | 20.04 Focal Fossa | amd64 |
| Ubuntu | 21.04 Hirsute Hippo | amd64 |
| Ubuntu | 21.10 Impish Indri | amd64 |
| Windows | Server 2019 | x64, x86 |
| macOS | 10.15 Catalina, 11 Big Sur | amd64, arm64, universal |
License
The YubiHSM 2 SDK is intended for use in development and production environments in conjunction with YubiHSM 2, pursuant to Yubico Toolset Software License Agreement. By downloading and installing the SDK you agree to the terms of this license.
The released SDK source code is licensed under the Apache 2.0 license.
Third party software included in the YubiHSM 2 SDK, and their respective licenses, are listed in the licenses directory inside the SDK package.
The YubiHSM 2 Device
The YubiHSM 2 is a USB-based, multi-purpose cryptographic device for servers. Its diminutive physical size is ideal for installation directly into internal or external server ports.
What’s in the SDK
The SDK contains tools to interface with YubiHSM 2. For more information about each of the main components, please see the component reference section.
| Resource | Description |
|---|---|
| bin/libcrpto-1_1-x64.dll | Pre-built OpenSSL (Windows only) |
| bin/yubihsm-setup | Deployment tool for YubiHSM 2 |
| bin/yubihsm-wrap | A tool to create wrapped importable objects offline |
| bin/yubihsm-connector | The connector, a tool for providing a common interface to the device |
| bin/yubihsm-shell | The shell, a REPL-style tool for interacting with YubiHSM 2 (and the connector) See Note (1) |
| include/pkcs11/pkcs11.h | Common and standard PKCS#11 functions and constants definitions |
| include/pkcs11/pkcs11y.h | Yubico-specific PKCS#11 functions and constants definitions |
| include/yubihsm.h | Library functions and constants definitions |
| lib/libyubihsm.{dylib,so} or in/libyubihsm.dll | Library binary to interact with YubiHSM 2 |
| lib/yubihsm_pkcs11.{dylib,so} or bin/yubihsm_pkcs11.dll | PKCS#11 module to interact with ubiHSM 2 |
| python-noarch/* | Python implementation of the library |
| yubihsm-cngprovider-windows-amd64.msi | Installer for CNG/KSP for Windows ADCS (Windows only) |
| yubihsm-connector-windows-amd64.msi | Installer for the connector (Windows only) |
Note (1) Read-Evaluation-Print-Loop, REPL
YubiHSM 2 FIPS
The YubiHSM 2 is FIPS 140-2 certified and listed on the NIST site under Certificate 3916. YubiHSM 2 FIPS devices include the text “FIPS” laser-etched onto the surface of the device, and support the FIPS Approved mode flag.
Placing a YubiHSM 2 into FIPS mode will require that all loaded objects have been deleted, which can be performed via a “Reset Device” command.
Putting into FIPS Mode
To configure the YubiHSM 2 into the FIPS Approved mode of operation:
| Step 1: | Use the “Set Option” service as follows: 4f000405000101 or put option 0 fips-mode 01. |
|---|---|
| Step 2: | Import new Authentication Keys to replace the default values. |
Validating the Mode
To check the mode of operation:
Use the “Get Option” service as follows: get option 0 fips-mode
01return code indicates the Approved mode00return code indicates the non-Approved mode
Taking it out of FIPS Mode
To configure the YubiHSM 2 into the non-Approved mode of operation:
| Step 1: | Delete all objects on the YubiHSM 2. |
|---|---|
| Step 2: | Use the “Set Option” service as follows: 4f000405000100 or put option 0 fips-mode 00. |
Getting Help
Documentation aiding in deploying and using the YubiHSM 2 is continuously updated on https://docs.yubico.com/ (this site). Additional support resources are available in the Yubico Knowledge Base.
Important
If you think you may have discovered a flaw in the product, Yubico welcomes your feedback. To report an issue that you suspect might be a bug, please submit a support request and provide as much detail as you can.
To submit a support request: https://support.yubico.com/hc/en-us