Klas Lindfors
127 lines
4.1 KiB
Plaintext
127 lines
4.1 KiB
Plaintext
Yubico PIV Tool
|
|
===============
|
|
|
|
Introduction
|
|
------------
|
|
|
|
The Yubico PIV tool is used for interacting with the Privilege and
|
|
Identification Card (PIV) applet on a https://www.yubico.com[YubiKey NEO].
|
|
|
|
With it you may generate keys on the device, importing keys and
|
|
certificates, and create certificate requests, and other operations.
|
|
A shared library and a command-line tool is included.
|
|
|
|
License
|
|
-------
|
|
|
|
This program is free software: you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation, either version 3 of the License, or
|
|
(at your option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
Additional permission under GNU GPL version 3 section 7
|
|
|
|
If you modify this program, or any covered work, by linking or
|
|
combining it with the OpenSSL project's OpenSSL library (or a
|
|
modified version of that library), containing parts covered by the
|
|
terms of the OpenSSL or SSLeay licenses, We grant you additional
|
|
permission to convey the resulting work. Corresponding Source for a
|
|
non-source form of such a combination shall include the source code
|
|
for the parts of OpenSSL used as well as that of the covered work.
|
|
|
|
Building
|
|
--------
|
|
|
|
After downloading and unpacking the package tarball, you build it as
|
|
follows.
|
|
|
|
./configure
|
|
make
|
|
sudo make install
|
|
|
|
The backend to use is decided at compile time, see the summary at the
|
|
end of the ./configure output. Use --with-backend=foo to chose
|
|
backend, replacing foo with the backend you want to use. The backends
|
|
available are "pcsc", "macscard", and "winscard" using the PCSC
|
|
interface, with slightly different shared library linkage and
|
|
header file names: "pcsc" is used under GNU-like systems, "macscard"
|
|
under Mac OS X, and "winscard" is used under Windows. In most
|
|
situations, running ./configure should automatically find the proper
|
|
backend to use.
|
|
|
|
Building from Git
|
|
-----------------
|
|
|
|
Recent versions of autoconf, automake, pkg-config and libtool must
|
|
be installed. Help2man is used to generate the manpages. Gengetopt
|
|
version 2.22.6 or later is needed for command line parameter handling.
|
|
|
|
Generate the build system using:
|
|
|
|
autoreconf --install
|
|
|
|
Then you follow the normal build instructions, see above.
|
|
To turn on all warnings add --enable-gcc-warnings to ./configure
|
|
|
|
Portability
|
|
-----------
|
|
|
|
The main development platform is Debian GNU/Linux. The project is
|
|
cross-compiled to Windows using MinGW (see windows.mk) using the PCSC
|
|
backend. It may also be built for Mac OS X (see mac.mk), also using
|
|
the PCSC backend.
|
|
|
|
Example Usage
|
|
-------------
|
|
|
|
For help text on all commands --help can be given to the command, for more
|
|
output --verbose or --verbose=2 may be added.
|
|
|
|
Generate a new ECC-P256 key on device in slot 9a, will print the public
|
|
key on stdout:
|
|
|
|
yubico-piv-tool -s 9a -A ECCP256 -a generate
|
|
|
|
Generate a certificate request with public key from stdin, will print
|
|
the resulting request on stdout:
|
|
|
|
yubico-piv-tool -s 9a -S '/CN=foo/OU=test/O=example.com/' -P 123456 \
|
|
-a verify -a request
|
|
|
|
Generate a self-signed certificate with public key from stdin, will print
|
|
the certificate, for later import, on stdout:
|
|
|
|
yubico-piv-tool -s 9a -S '/CN=bar/OU=test/O=example.com/' -P 123456 \
|
|
-a verify -a selfsign
|
|
|
|
Import a certificate from stdin:
|
|
|
|
yubico-piv-tool -s 9a -a import-certificate
|
|
|
|
Set a random chuid, import a key and import a certificate from a PKCS12
|
|
file with password test, into slot 9c:
|
|
|
|
yubico-piv-tool -s 9c -i test.pfx -K PKCS12 -p test -a set-chuid \
|
|
-a import-key -a import-cert
|
|
|
|
Change the management key used for administrative authentication:
|
|
|
|
yubico-piv-tool -n 0807605403020108070605040302010807060504030201 \
|
|
-a set-mgm-key
|
|
|
|
Delete a certificate in slot 9a:
|
|
|
|
yubico-piv-tool -a delete-certificate -s 9a
|
|
|
|
Show some information on certificates and other data:
|
|
|
|
yubico-piv-tool -a status
|