Introduction
What is YubiHSM 2?
The YubiHSM 2 is a Hardware Security Module that is within reach of 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.
Documentation Overview
Note
YubiHSM 2 SDK documentation and usage guides are enhanced continuously. Please check back regularly to see what’s new.
The purpose of this documentation is both to provide detailed descriptions of YubiHSM 2 concepts and to work as a reference for commands and APIs provided. Before setting up YubiHSM 2 for the first time, familiarize yourself with the basic concepts and terminology used in the product documentation contained within these pages as well as in the software itself.
- Releases provides access to release notes, downloads, and known issues and limitations.
- Product Overview (this section) gives a high-level description of the YubiHSM 2 offering; product specifications, contents of the SDK, and how to get help.
- Concepts explains the foundational concepts used; understanding of these concepts is necessary in order to use YubiHSM 2.
- Commands provides an inventory of all available commands, with yubihsm-shell usage examples.
- Component Reference is a collection of reference materials for the components included in the SDK: the core libraries, the PKCS#11 module, the Shell, the Key Storage Provider, and more.
- Usage Guides YubiHSM 2 Administration and Usage Tasks, YubiHSM 2 for Active Directory Certificate Services Guide, Introduction to YubiHSM 2 Windows Deployment Guide, YubiHSM 2 for MS Host Guardian Service Guide, and YubiHSM 2 for MS SQL Server Guide, contains a number of guides and examples for using YubiHSM 2.
- Backup and Restore informs about how to back up keys, and how to restore from backups.
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
Getting Help
Documentation aiding in deploying and using the YubiHSM 2 is continuously updated on https://developers.yubico.com/YubiHSM2 (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