err.no Git - yubikey-personalization/blob - README

   1 Installation of the Yubikey Personalization package
   2 ===================================================
   3
   4 Yubikey Personalization
   5 -----------------------
   6
   7 The YubiKey Personalization package contains a library and command
   8 line tool used to personalize (i.e., set a AES key) YubiKeys.
   9
  10 Documentation
  11 -------------
  12
  13 The complete reference manual on the YubiKey is required reading if
  14 you want to understand the entire picture and what each parameter
  15 does.  Download it from http://www.yubico.com/
  16
  17 Dependencies
  18 ------------
  19
  20 Getting and installing dependencies depends on your operating systems,
  21 we give example for some flavours.  If you know how to install
  22 dependencies on other systems, let us know.  Debian hints should apply
  23 to Debian derivatives as well, including Ubuntu.
  24
  25 Yubico-c is needed, see: http://opensource.yubico.com/yubico-c/
  26
  27   Debian:           apt-get install libyubikey-dev
  28
  29 Pkg-config simplify finding other dependencies, see:
  30 http://www.freedesktop.org/wiki/Software/pkg-config
  31
  32   Debian:           apt-get install pkg-config
  33
  34 Yubikey-personalization depends on libusb or libusb-1, so you will
  35 have to get it.  We recommend using libusb-1.
  36
  37   Debian libusb-1:  apt-get install libusb-1.0-0-dev
  38   Debian libusb:    apt-get install libusb-dev
  39   Fedora:           yum install libusb-devel
  40
  41 The JSON library is an optional dependency, see:
  42 https://github.com/json-c/json-c/wiki
  43
  44   Debian:           apt-get install libjson0-dev
  45
  46 You need json-c version 0.10 or later to get pretty printing of JSON
  47 output.  This project will build with version 0.9 too, but will not
  48 pretty print the JSON output.
  49
  50 License
  51 -------
  52
  53 The project is licensed under a BSD license.  See the file COPYING for
  54 exact wording.  For any copyright year range specified as YYYY-ZZZZ in
  55 this package note that the range specifies every single year in that
  56 closed interval.
  57
  58 Building from Git
  59 -----------------
  60
  61 Skip to the next section if you are using an official packaged
  62 version.
  63
  64 You may check out the sources using Git with the following command:
  65
  66 -----------
  67   git clone git://github.com/Yubico/yubikey-personalization.git
  68 -----------
  69
  70 This will create a directory 'yubikey-personalization'.  Enter the directory:
  71
  72 -----------
  73   cd yubikey-personalization
  74 -----------
  75
  76 Autoconf, automake and libtool must be installed.
  77
  78 Generate the build system using:
  79
  80 -----------
  81   autoreconf --install
  82 -----------
  83
  84 Building
  85 --------
  86
  87 The build system uses Autoconf, to set up the build system run:
  88
  89 -----------
  90   ./configure
  91 -----------
  92
  93 Then build the code, run the self-test and install the binaries:
  94
  95 -----------
  96   make check install
  97 -----------
  98
  99 Using
 100 -----
 101
 102 WARNING: By using this tool you will destroy the AES key in your
 103 YubiKey.  This prevents it from being useful against Yubico's
 104 validation server.  It is possible to upload a new AES key to Yubico,
 105 using a random YubiKey prefix, to restore it.  But it is not possible
 106 to get back your old yubikey prefix if you decide to re-program your
 107 YubiKey.
 108
 109 IMPORTANT: When running any of the utils that need to access the YubiKey
 110 you will either need to run as root, or you will have to have made sure
 111 that the current user has permission to access the device. These
 112 permissions can be set up by copying the udev rules files
 113 (https://github.com/Yubico/yubikey-personalization/blob/master/69-yubikey.rules[69-yubikey.rules]
 114 and https://github.com/Yubico/yubikey-personalization/blob/master/70-yubikey.rules[70-yubikey.rules]) to /etc/udev/rules.d/
 115
 116 With that out of the way, here is how you would program a YubiKey with
 117 an all-zero AES key and a dummy prefix:
 118
 119 -----------
 120 $ ./ykpersonalize -ofixed=cccccccccccc -a00000000000000000000000000000000
 121 Firmware version 1.3.1 Touch level 9840 Program sequence 10
 122 Configuration data to be written to key configuration 1:
 123
 124 fixed: m:cccccccccccc
 125 uid: h:000000000000
 126 key: h:00000000000000000000000000000000
 127 acc_code: h:000000000000
 128 ticket_flags: APPEND_CR
 129 config_flags:
 130
 131 Commit? (y/n) [n]: y
 132 $
 133 -----------
 134
 135 Using the "ykparse" tool from the yubico-c package, you can check that
 136 the OTPs are correct.  For example:
 137
 138 -----------
 139 $ ykparse 00000000000000000000000000000000 ccccccccccccdkrkedgchtlfefghcekefhlifbchijrd
 140 warning: overlong token, ignoring prefix: cccccccccccc
 141 Input:
 142   token: dkrkedgchtlfefghcekefhlifbchijrd
 143           29 c9 32 50 6d a4 34 56 03 93 46 a7 41 06 78 c2
 144   aeskey: 00000000000000000000000000000000
 145           00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 146 Output:
 147           00 00 00 00 00 00 01 00 53 ea 63 00 6f 9e c4 24
 148
 149 Struct:
 150   uid: 00 00 00 00 00 00
 151   counter: 1 (0x0001)
 152   timestamp (low): 59987 (0xea53)
 153   timestamp (high): 99 (0x63)
 154   session use: 0 (0x00)
 155   random: 40559 (0x9e6f)
 156   crc: 9412 (0x24c4)
 157
 158 Derived:
 159   cleaned counter: 1 (0x0001)
 160   modhex uid: cccccccccccc
 161   triggered by caps lock: no
 162   crc: F0B8
 163   crc check: ok
 164 $
 165 -----------
 166
 167 To program a YubiKey in static mode, you use the -ostatic-ticket flag
 168 as follows:
 169
 170 -----------
 171 $  ./ykpersonalize -ofixed=cccccccccccc -a00000000000000000000000000000000 -ostatic-ticket
 172 Firmware version 1.3.1 Touch level 9856 Program sequence 11
 173 Configuration data to be written to key configuration 1:
 174
 175 fixed: m:cccccccccccc
 176 uid: h:000000000000
 177 key: h:00000000000000000000000000000000
 178 acc_code: h:000000000000
 179 ticket_flags: APPEND_CR
 180 config_flags: STATIC_TICKET
 181
 182 Commit? (y/n) [n]: y
 183 $
 184 -----------
 185
 186 To program a YubiKey in static mode with a strongly looking password
 187 (i.e., also containing numeric and upper case letters), you use the
 188 -ostatic-ticket flag together with -ostrong-pw1 and -ostrong-pw2 (note
 189 YubiKey 2.0 only!) as follows:
 190
 191 -----------
 192 $  ./ykpersonalize -ofixed=cccccccccccc -a00000000000000000000000000000000 -ostatic-ticket -ostrong-pw1 -ostrong-pw2
 193 Firmware version 2.0.0 Touch level 1792 Program sequence 3
 194 Configuration data to be written to key configuration 1:
 195
 196 fixed: m:cccccccccccc
 197 uid: h:000000000000
 198 key: h:00000000000000000000000000000000
 199 acc_code: h:000000000000
 200 ticket_flags: APPEND_CR
 201 config_flags: STATIC_TICKET|STRONG_PW1|STRONG_PW2
 202
 203 Commit? (y/n) [n]: y
 204 $
 205 -----------
 206
 207 Alternatively on a YubiKey 2.0, you can program the second configuration, which
 208 defaults to be the static key configuration:
 209
 210 -----------
 211 $  ./ykpersonalize -ofixed=cccccccccccc -a00000000000000000000000000000000 -2
 212 Firmware version 2.0.0 Touch level 1792 Program sequence 3
 213 Configuration data to be written to key configuration 2:
 214
 215 fixed: m:cccccccccccc
 216 uid: h:000000000000
 217 key: h:00000000000000000000000000000000
 218 acc_code: h:000000000000
 219 ticket_flags: APPEND_CR
 220 config_flags: STATIC_TICKET|STRONG_PW1|STRONG_PW2
 221
 222 Commit? (y/n) [n]: y
 223 $
 224 -----------
 225
 226 To program a YubiKey with a lock code (to prevent others from easily
 227 reprogramming it), you use the -oaccess= flag as follows:
 228
 229 -----------
 230 $ ./ykpersonalize -ofixed=vvvecdcedvjj -a00000000000000000000000000000000 -oaccess=001100001100
 231 Firmware version 2.0.0 Touch level 1792 Program sequence 3
 232 Configuration data to be written to key configuration 1:
 233
 234 fixed: m:vvvecdcedvjj
 235 uid: h:000000000000
 236 key: h:00000000000000000000000000000000
 237 acc_code: h:001100001100
 238 ticket_flags: APPEND_CR
 239 config_flags:
 240
 241 Commit? (y/n) [n]: y
 242 $
 243 -----------
 244
 245 To re-program a YubiKey that has a lock code set, you use the
 246 -cXXX.. flag as follows:
 247
 248 -----------
 249 $ ./ykpersonalize -c001100001100 -ofixed=vvvecdcedvjj -a00000000000000000000000000000000 -oaccess=001100223300
 250 Firmware version 2.0.0 Touch level 1792 Program sequence 3
 251 Configuration data to be written to key configuration 1:
 252
 253 fixed: m:vvvecdcedvjj
 254 uid: h:000000000000
 255 key: h:00000000000000000000000000000000
 256 acc_code: h:001100223300
 257 ticket_flags: APPEND_CR
 258 config_flags:
 259
 260 Commit? (y/n) [n]: y
 261 $
 262 -----------
 263
 264 To disable the lock code on a YubiKey, program it with a lock code set
 265 to zeros.  For example:
 266
 267 -----------
 268 $ ./ykpersonalize -c001100001133 -ofixed=vvvecdcedvjj -a00000000000000000000000000000003 -oaccess=000000000000
 269 Firmware version 2.0.0 Touch level 1792 Program sequence 7
 270 Configuration data to be written to key configuration 1:
 271
 272 fixed: m:vvvecdcedvjj
 273 uid: h:000000000000
 274 key: h:00000000000000000000000000000000
 275 acc_code: h:000000000000
 276 ticket_flags: APPEND_CR
 277 config_flags:
 278
 279 Commit? (y/n) [n]: y
 280 $
 281 -----------
 282
 283 Feedback
 284 --------
 285
 286 See the Google Group yubico-devel:
 287 http://groups.google.com/group/yubico-devel