Merge tag 'v1.15.1'

[yubikey-personalization] / ykpersonalize.1

.\" Copyright (c) 2009-2014 Yubico AB
.\" Copyright (C) 2009, 2010 Tollef Fog Heen <tfheen@err.no>
.\" 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.
.\"
.\" The following commands are required for all man pages.
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH ykpersonalize "1" "August 2009" "yubikey-personalization"
.SH NAME
ykpersonalize - personalize YubiKey OTP tokens
.SH SYNOPSIS
.B ykpersonalize
[\fI-1\fR | \fI-2\fR] [\fI-sfile\fR] [\fI-ifile\fR] [\fI-fformat\fR] [\fI-axxx\fR] [\fI-cxxx\fR]
[\fI-ooption\fR] [\fI-y\fR] [\fI-v\fR] [\fI-d\fR] [\fI-h\fR] [\fI-n\fR] [\fI-t\fR] [\fI-u\fR] [\fI-x\fR]
[\fI-z\fR] [\fI-m\fR] [\fI-S\fR] [\fI-V\fR]
.\".SH DESCRIPTION
.\" Add any additional description here
.SH OPTIONS
.PP
Set the AES key, user ID and other settings in a YubiKey.  For the complete
explanation of the meaning of all parameters, see the reference
manual:
.URL "http://yubico.com/files/YubiKey_manual-2.0.pdf" "YubiKey manual"
.TP
\fB\-1\fR
change the first configuration.  This is the default and is
normally used for true OTP generation.  In this configuration,
the option flag \fB-oappend-cr\fR is set by default.
.TP
\fB\-2\fR
change the second configuration.  This is for YubiKey II only and is
then normally used for static key generation.  In this configuration,
the option flags \fB-oappend-cr\fR, \fB-ostatic-ticket\fR, \fB-ostrong-pw1\fR,
\fB-ostrong-pw2\fR and \fB-oman-update\fR are set by default.
.TP
\fB-z\fR
delete configuration in selected slot
.TP
\fB\-s\fIfile\fR
save configuration to file instead of key.
(if file is -, send to stdout)
.TP
\fB\-i\fIfile\fR
read configuration from file.
(if file is -, read from stdin)
.TP
\fB\-f\fIformat\fR
format to be used with \fB-s\fR and \fB-i\fR.
Valid options are \fBycfg\fR and \fBlegacy\fR.
.TP
\fB\-a\fR[\fIxxx\fR]
the AES secret key as a 32 (or 40 for OATH-HOTP/HMAC CHAL-RESP) char hex value (not modhex) (none to prompt for key on stdin)
If \fB\-a\fR is not used a random key will be generated.
.TP
\fB\-c\fIxxx\fR
A 12 char hex value (not modhex) to use as access code for
programming.
NOTE: this does NOT SET the access code, that's done with \fB-oaccess\fI=\fR.
.TP
\fB\-o\fIoption\fR
change configuration option.  Possible option arguments are
.RS
.TP
\fBfixed\fR=\fIfffffffffff\fR
The modhex \fIpublic identity\fR of the YubiKey, 0-32 characters long (encoding
up to 16 bytes).
It's possible to give the identity in hex as well, just prepend the
value with `h:'. The fixed part is emitted before the OTP when the
button on the YubiKey is pressed. It can be used as an identifier for
the user, for example.
.TP
\fBuid\fR=\fIuuuuuu\fR
The uid part of the generated OTP, also called \fIprivate identity\fR, in hex.
Must be 12 characters long. The uid is 6 bytes of static data that is included
(encrypted) in every OTP, and is used to validate that an OTP was in fact encrypted
with the AES key shared between the YubiKey and the validation service. It cannot
be used to identify the YubiKey as it is only readable to those that know
the AES key.
.TP
\fBaccess\fR=\fIfffffffffff\fR
New hex access code to set. Must be 12 characters long.
If an access code is set, it will be required for subsequent reprogramming of the YubiKey.
.TP
\fBoath-imf\fR=\fIxxx\fR
Set OATH Initial Moving Factor. This is the initial counter value for the YubiKey.
This should be a value between 0 and 1048560, evenly dividable by 16.
.TP
[\-]\fIticket-flag\fR
Set/clear ticket flag, see the section `Ticket flags\&'
.TP
[\-]\fIconfiguration-flag\fR
Set/clear ticket flag, see the section `Configuration flags\&'
.RE
.TP
\fB-y\fR
always commit without prompting
.TP
\fB-d\fR
dry-run, run without writing a YubiKey
.TP
\fB-v\fR
Be more verbose
.TP
\fB-h\fR
Help
.TP
\fB-V\fR
Version
.TP
\fBYubiKey NEO only\fR
.RS
.TP
\fB-m mode\fR
set device configuration for the YubiKey NEO.  It is parsed in the form
\fImode:cr_timeout:autoeject_timeout\fR
.br
where mode is:
.br
0    HID device only.
.br
1    CCID device only.
.br
2    HID/CCID composite device.
.br
Add 80 to set MODE_FLAG_EJECT, for example: 81
.br
cr_timeout is the timeout in seconds for the YubiKey to wait on button press for challenge response (default is 15)
.br
autoeject_timeout is the timeout in seconds before the card is automatically ejected in mode 81
.TP
\fB-S\fI0605...\fR
set the scanmap to be used with the YubiKey NEO.  It must be 45 unique
bytes as 90 characters.  Leave argument empty to reset to the YubiKey's default.
The scanmap must be sent in the order:
.br
\fIcbdefghijklnrtuvCBDEFGHIJKLNRTUV0123456789!\\t\\r\fR.
.br
the default scanmap in the YubiKey is:
.br
\fI06050708090a0b0c0d0e0f111517181986858788898a8b8c8d8e8f
.br
9195979899271e1f202122232425269e2b28\fR
.br
an example for simplified us dvorak would be:
.br
\fI0c110b071c180d0a0619130f120e09378c918b879c988d8a869993
.br
8f928e89b7271e1f202122232425269e2b28\fR
.br
or for a french azerty keyboard (digits are shifted):
.br
\fI06050708090a0b0c0d0e0f111517181986858788898a8b8c8d8e8f
.br
9195979899a79e9fa0a1a2a3a4a5a6382b28\fR
.br
and a turkish example (has a dotless i instead of usual i):
.br
\fI06050708090a0b340d0e0f111517181986858788898a8b8c8d8e8f
.br
9195979899271e1f202122232425269e2b28\fR
.br
Note that you must remove any whitespace present in these examples
before using the values.
.TP
\fB-n URI\fR
Program NFC NDEF URI
.TP
\fB-t text\fR
Program NFC NDEF text
.RE
.TP
\fBYubiKey 2.3 and above\fR
.RS
.TP
\fB-u\fR
Update existing configuration, rather than overwriting
.TP
\fB-x\fR
Swap configuration slot 1 and 2 inside the YubiKey
.RE
.SH Ticket flags
.TP
[\-]\fBtab-first\fR
Send a tab character as the first character.  This is usually used to move
to the next input field.
.TP
[\-]\fBappend-tab1\fR
Send a tab character between the fixed part and the one-time password
part. This is useful if you have the fixed portion equal to the user
name and two input fields that you navigate between using tab.
.TP
[\-]\fBappend-tab2\fR
Send a tab character as the last character.
.TP
[\-]\fBappend-delay1\fR
Add a half-second delay before sending the one-time password part.
.TP
[\-]\fBappend-delay2\fR
Add a half-second delay after sending the one-time password part.
.TP
[\-]\fBappend-cr\fR
Send a carriage return after sending the one-time password part.
.TP
\fBYubiKey 2.0 firmware and above\fR
.TP
[\-]\fBprotect-cfg2\fR
When written to configuration 1, block later updates to configuration
2.  When written to configuration 2, prevent configuration 1 from
having the lock bit set.
.TP
\fBYubiKey 2.1 firmware and above\fR
.TP
[\-]\fBoath-hotp\fR
Set OATH-HOTP mode rather than YubiKey mode.  In this mode, the token
functions according to the OATH-HOTP standard.
.TP
\fBYubiKey 2.2 firmware and above\fR
.TP
[\-]\fBchal-resp\fR
Set challenge-response mode.
.SH Configuration flags
[\-]\fBsend-ref\fR
Send a reference string of all 16 modhex characters before the fixed
part.  This can not be combined with the \fB-ostrong-pw2\fR flag.
.TP
[\-]\fBpacing-10ms\fR
Add a 10ms delay between key presses.
.TP
[\-]\fBpacing-20ms\fR
Add a 20ms delay between key presses.
.TP
[\-]\fBstatic-ticket\fR
Output a fixed string rather than a one-time password.  The password
is still based on the AES key and should be hard to guess and
impossible to remember.
.TP
\fBYubiKey 1.x firmware only\fR
.TP
[\-]\fBticket-first\fR
Send the one-time password rather than the fixed part first.
.TP
[\-]\fBallow-hidtrig\fR
Allow trigger through HID/keyboard by pressing caps-, num or
scroll-lock twice.  Not recommended for security reasons.
.TP
\fBYubiKey 2.0 firmware and above\fR
.TP
[\-]\fBshort-ticket\fR
Limit the length of the static string to max 16 digits.  This flag
only makes sense with the \fB-ostatic-ticket\fR option.  When
\fB-oshort-ticket\fR is used without \fB-ostatic-ticket\fR it will
program the YubiKey in "scan-code mode", in this mode the key sends
the contents of fixed, uid and key as raw keyboard scancodes.  For
example, by using the fixed string \fIh:8b080f0f122c9a12150f079e\fR in
this mode it will send \fIHello World!\fR on a qwerty keyboard.  This
mode sends raw scan codes, so output will differ between keyboard layouts.
.TP
[\-]\fBstrong-pw1\fR
Upper-case the two first letters of the output string.  This is for
compatibility with legacy systems that enforce both uppercase and
lowercase characters in a password and does not add any security.
.TP
[\-]\fBstrong-pw2\fR
Replace the first eight characters of the modhex alphabet with the
numbers 0 to 7.  Like \fB-ostrong-pw1\fR, this is intended to support
legacy systems.
.TP
[\-]\fBman-update\fR
Enable user-initiated update of the static password.  Only makes sense
with the \fB-ostatic-ticket\fR option.
.TP
\fBYubiKey 2.1 firmware and above\fR
.TP
[\-]\fBoath-hotp8\fR
When set, generate an 8-digit HOTP rather than a 6-digit one.
.TP
[\-]\fBoath-fixed-modhex1\fR
When set, the first byte of the fixed part is sent as modhex.
.TP
[\-]\fBoath-fixed-modhex2\fR
When set, the first two bytes of the fixed part is sent as modhex.
.TP
[\-]\fBoath-fixed-modhex\fR
When set, the fixed part is sent as modhex.
.TP
\fBoath-id=m:OOTTUUUUUUUU\fR
Configure OATH token id with a provided value.  See description of
this option under the 2.2 section for details, but note that a YubiKey
2.1 key can't report its serial number and thus a token identifier value
must be specified.
.TP
\fBYubiKey 2.2 firmware and above\fR
.TP
[\-]\fBchal-yubico\fR
Yubico OTP challenge-response mode.
.TP
[\-]\fBchal-hmac\fR
Generate HMAC-SHA1 challenge responses.
.TP
[\-]\fBhmac-lt64\fR
Calculate HMAC on less than 64 bytes input.  Whatever is in the last byte
of the challenge is used as end of input marker (backtracking from end of payload).
.TP
[\-]\fBchal-btn-trig\fR
The YubiKey will wait for the user to press the key (within 15 seconds) before
answering the challenge.
.TP
[\-]\fBserial-btn-visible\fR
The YubiKey will emit its serial number if the button is pressed during power-up.
.TP
[\-]\fBserial-usb-visible\fR
The YubiKey will indicate its serial number in the USB iSerial field.
.TP
[\-]\fBserial-api-visible\fR
The YubiKey will allow its serial number to be read using an API call.
.TP
\fBoath-id[=m:OOTTUUUUUUUU]\fR
Configure OATH token id with a provided value, or if used without a value use the
standard YubiKey token identifier.

The standard OATH token id for a Yubico YubiKey is (modhex) OO=ub, TT=he,
(decimal) UUUUUUUU=serial number.

The reason for the decimal serial number is to make it easy for humans to correlate
the serial number on the back of the YubiKey to an entry in a list of associated
tokens for example.  Other encodings can be accomplished using the appropriate
oath-fixed-modhex options.

Note that the YubiKey must be programmed to allow reading its serial number,
otherwise automatic token id creation is not possible.

See section "5.3.4 - OATH-HOTP Token Identifier" of the
.URL "http://yubico.com/files/YubiKey_manual-2.0.pdf" "YubiKey manual"
for further details.
.TP
\fBYubiKey 2.3 firmware and above\fR
.TP
[\-]\fBuse-numeric-keypad\fR
Send scancodes for numeric keypad keypresses when sending digits - helps with some
keyboard layouts.
.TP
[\-]\fBfast-trig\fR
Faster triggering when only configuration 1 is available.
.TP
[\-]\fBallow-update\fR
Allow updating of certain parameters in a configuration at a later time.
.TP
[\-]\fBdormant\fR
Hides/unhides a configuration stored in a YubiKey.
.TP
\fBYubiKey 2.4/3.1 firmware and above\fR
.TP
[\-]\fBled-inv\fR
Inverts the behaviour of the led on the YubiKey.

.SH OATH-HOTP Mode
When using OATH-HOTP mode, a HMAC key of 160 bits (20 bytes, 40 chars of hex)
can be supplied with \fB\-a\fR.
.PP

.SH Challenge-response Mode
In \fBCHAL-RESP\fR mode, the token will NOT generate any keypresses when the button
is pressed (although it is perfectly possible to have one slot with a keypress-generating
configuration, and the other in challenge-response mode).  Instead, a program capable of
sending USB HID feature reports to the token must be used to send it a challenge, and
read the response.

.SH Modhex
Modhex is a way of writing hex digits where the \(lqdigits\(rq are
chosen for being in the same place on most keyboard layouts.
.TP
To convert from hex to modhex, you can use
.RS
tr "[0123456789abcdef]" "[cbdefghijklnrtuv]"
.RE
.TP
To convert the other way, use
.RS
tr "[cbdefghijklnrtuv]" "[0123456789abcdef]"
.RE

.SH BUGS
Report ykpersonalize bugs in
.URL "https://github.com/Yubico/yubikey-personalization/issues" "the issue tracker"
.SH "SEE ALSO"
The
.URL "http://opensource.yubico.com/yubikey-personalization/" "ykpersonalize home page"
.PP
YubiKeys can be obtained from
.URL "http://www.yubico.com/" "Yubico" "."