Introduction
Use the Yubico PIV tool for interacting with the Personal Identity Verification (PIV) application on a YubiKey.
Through the Yubico PIV tool, you can generate keys on the device, import keys and certificates, and create certificate requests, and other operations. A shared library and a command-line tool, yubico-piv-tool, is included.
The Yubico PIV tool was designed to interact with and manage the PIV functions alone. Built on the C ykpiv library, the PIV tool provides a CLI to access all of the functionality supported on the PIV function of the YubiKey. While the PIV tool allows for the CLI to be used as part of a scripted process, the lack of support beyond the PIV functions means that it is less script-friendly than ykman. However, as a purpose built interface on just the ykpiv library, the PIV tool is an excellent reference architecture for supporting the YubiKey as a PIV smart card natively.
The PIV tool also provides a PKCS#11 module, called YKCS11, that can be used to expose the YubiKey’s smart card functionality to applications that communicate with hard tokens through the PKCS#11 API. For example, OpenSSL, OpenSSH, JAVA, FireFox and the like.
Use the PIV tool when ykman does not have a specific command, or when testing the PIV functionality of the YubiKey. On POSIX platforms, PIV tool requires pcscd to be pre-installed.
- See the Yubico PIV Tool Release Notes for PIV Tool versions.
- See the PIV Introduction on developers.yubico.com for information about performing RSA or ECC sign/decrypt operations using a private key stored on the YubiKey smartcard, through common interfaces like PKCS#11.
PIV Standard
PIV, or FIPS 201, is a US government standard. It enables RSA or ECC sign/encrypt operations using a private key stored on a smartcard (such as the YubiKey), through common interfaces like PKCS#11.
YubiKeys support the PIV card interface specified in NIST SP 800-73 document Cryptographic Algorithms and Key Sizes for Personal Identity Verification. PIV enables you to perform RSA or ECC sign/decrypt operations using a private key stored on the smartcard, through common interfaces like PKCS#11. This document contain the library, tools and PKCS#11 module to interact with the hardware functionality.
You can read more about the PIV standards here: PIV Standards
PIV is primarily used for non-web applications. It has built-in support under Windows, and can be used on macOS and Linux via the OpenSC project.
PIV Tool Design
The Yubico PIV tool was designed to interact with and manage the PIV functions alone. Built on the C ykpiv library, the PIV tool provides a CLI to access all of the functionality supported on the PIV function of the YubiKey. While PIV tool allows for the CLI to be used as part of a scripted process, the lack of support beyond the PIV functions means that it is less script-friendly than ykman. However, as a purpose built interface on just the ykpiv library, the PIV tool is an excellent reference architecture for supporting the YubiKey as a PIV smart card natively.
The PIV tool also provides a PKCS#11 module, called YKCS11, that can be used to expose the YubiKey’s smart card functionality to applications that communicate with hard tokens through the PKCS#11 API; applications like OpenSSL, OpenSSH, JAVA, FireFox and the like.
Use the PIV tool when ykman does not have a specific command, or when testing the PIV functionality of the YubiKey. On POSIX platforms, PIV tool requires pcscd to be pre-installed.
PIV Usage Guides
For information and examples on what you can do with a PIV enabled YubiKey, see https://developers.yubico.com/PIV/.
General Information
The default PIN code is 123456. The default PUK code is 12345678.
For firmware 5.7 and above: The default AES-192 management key (9B) is 010203040506070801020304050607080102030405060708.
For firmware 5.4 and below: The default 3DES management key (9B) is 010203040506070801020304050607080102030405060708.
The following key slots exists:
- 9A, 9C, 9D, 9E: RSA 1024, RSA 2048, ECC secp256r1 or ECC secp384r1 keys (algorithms 6, 7, 11 respectively).
- 9B: Triple-DES key (algorithm 3) for PIV management.
The maximum size of stored objects is 2025/3049 bytes for current versions of YubiKey NEO and YubiKey 4, respectively.
Currently all functionality are available over both contact and contactless interfaces (contrary to what the specifications mandate).
Software
Card management has been tested with the tools from the OpenSC project, specifically piv-tool, and Yubico PIV software. Basic features should work with any PIV compliant middleware.
https://github.com/OpenSC/OpenSC/wiki
https://developers.yubico.com/yubico-piv-tool/
https://developers.yubico.com/yubikey-piv-manager/
License
In general the project is covered by the following BSD license. The file ykcs11/pkcs11.h has additional copyright and licensing information, please see it for more information.
Copyright (c) 2014-2020 Yubico AB
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.