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

  • 01 return code indicates the Approved mode
  • 00 return 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