Yubico Forum

We have pretty silently added a Windows personalization API for Yubikeys and due to the amount of support questions, it seems somewhat appropriate to give a primer on the basics and the programming model.

An initial word of caution: Using the personalization API would overwrite your current configuration data. If you have a key that is configured to work with the Yubico authentication server, this function will no longer work.

First of all, where do I get it ?
The configuration component and sample code is available as an installable MSI at http://www.yubico.com/developers/personalization/

Why Windows ?
The low-level interface to communicate with USB devices differs a lot between operating systems. We made the first reference implementation for Windows and decided to make it available as a COM/ActiveX component.

Why COM/ActiveX ?
COM provides a pretty nice encapsulation and allow it to be used in a variety of settings, from simple interfacing to most programming languages to an add-in in an Internet Explorer web page. Although some people could argue that a .net implementation would be more fashionable, interfacing a COM component in a .net environment is straightforward, but a .net assembly in a Win32 setting is pretty useless.

Any plans outside Windows environments ?
Absolutely - we've posted a basic LibUSB embryo on Google Code with the hope that someone picks up the ball. If not, we'll give it a shot later on, but we have quite a few things on the agenda so it may take some time. Check it out at http://code.google.com/p/yubico-usb-win32/ LibUSB is an USB interface encapsulation that should allow pretty painless portability between a variety of OSes, including Win32, MacOS and Linux. Check it out at http://libusb.wiki.sourceforge.net/

Before you tell about the concepts, is there any documentation available ?
There is a PDF included in the installer that describes the concepts and the programming model. This one should provide reasonably complete reference to develop an application from scratch.

Yeah, RTFM, RTFM... Tell me the basics and I might read it later...
Without going into the specifics on how COM works, the component works by the means of properties that can be set and a few methods that can be invoked. Optionally, events/callbacks can be used to get asyncronous notifications.

Configuring a Yubikey with a 6-byte pubic id, a private id, an AES key and a trailing CR is straightforward. The following pseudo-code illustrates how

ykStaticId = '471158125913'
ykUID = '123456789abc'
ykKey = '277e34c4f584be8b1d1268d2c70af8c'
ykFlagProperty(ykFLAG_APPEND_CR) = TRUE

IF ykProgram = ykOK THEN
Success
ELSE
Failure
ENDIF

What are these flag properties ? What can I do with them ?
All binary kind of on-off properties are set with these flags. The following flags can be set:

ykFLAG_TAB_FIRST - Send TAB as first character
ykFLAG_APPEND_TAB1 - Send TAB after first part
ykFLAG_APPEND_TAB2 - Send TAB after second part
ykFLAG_APPEND_DELAY1 - Append a short delay after first part is sent
ykFLAG_APPEND_DELAY2 - Append a short delay after second part is sent
ykFLAG_APPEND_CR - Append a CR after last character
ykFLAG_SEND_REF - Send a reference string first. This sends the entire modhex alphabet as a prefix
ykFLAG_TICKET_FIRST - Send the OTP part first and then the ID part, i.e. swap order of static ID and OTP
ykFLAG_PACING_10MS - Add 10 ms intra-character pacing
ykFLAG_PACING_20MS - Add 20 ms intra-character pacing
ykFLAG_ALLOW_HIDTRIG - Allow trigger by CAPS and NUM (works in Windows environments only)
ykFLAG_STATIC_TICKET - The key will generate static tickets only. Requires firmware 1.3.0 or later

Can I change a single property on an already configured key without changing what's already there ?
No - all properties are updated at ykProgram

Do I need to restore all properties after an ykProgram to a known value ?
All properties are preserved until changed. Invoking the ykClear method resets all properties to null / FALSE values.

Any examples included ?
There are sample code examples included for Visual C++, Visual Basic and ActiveX component usage in a HTML page

What prevents anyone from using this component to sabotage or hijack my issued keys ?
You can set a 6-byte configuration key using the ykNewPWD property. If set, the ykCurPWD needs to be set prior to any programming operation. The default is that this feature is disabled

I programmed a key and now it is just flashing every three seconds or so. What's wrong ?
This means that the key has been set to unconfigured mode, i.e. the factory default state where no valid configuration is present. Calling ykProgram without setting any property to any value causes this to happen.

What about the callbacks/events you mentioned ?
If desired, the component can generate an asychronous event when a device is inserted or removed. This can be useful to avoid having the application to poll for a device insert. In an automated setting, the ykInserted event notification can be used to automatically trigger a program operation. The ykRemoved notification can then be used to restore the state machine to a waiting-for-key-insert state.

What is the ykEnableDebug property ?
It is a feature for testing that the calling code does what you expect it to do. As each property or method is invoked, a debug message box is displayed with arguments if applicable.


Just a few starting topics... Please post your further questions as they come up.

Finally and maybe stated ad nauseam: Remember that using the configuration API will overwrite your current configuration. Evaluation keys configured to work with the Yubico authentication server will no longer work there if the configuration is changed !

Regards,

JakobE
Hardware- and firmware guy @ Yubico

For configuring the token (for private use), what's the best practice for setting ykStaticId, ykUID, ykKey?

ykStaticId : max 16 bytes? min?
ykUID : max 06 bytes? min?
ykKey : 16 bytes only?

How best to generate ykKey?

How can we use the reference string, ykFLAG_SEND_REF? How is it used to map values to modHex?

We are working on interoperability guidelines and will publish them when we’re finished. The plan is to launch a scheme where public ids will be designed never to clash and furthermore have a way to optionally determine who are handling the verification of a particular Yubikey.

Until then, there are a few rules to follow

The public id is a variable string with 0 – 16 bytes length = 0 – 32 characters

- The public id does not need to be linked to any relevant identity for the Yubikey holder in place. The concept behind the public id is to allow a quick database lookup for the appropriate AES key for the OTP being validated.

- In a private context, you don’t need to assign a public ID if you don’t want to. Then all Yubikeys in your own “realm” will share the same AES key. After decryption, the private ID is used to determine which user is assigned to the particular Yubikey.

- Yubico’s evaluation keys all have a fixed 6-bytes public ID assigned to them

- Any length from 0 to 3 bytes public ID is free to assign for anyone without restrictions.

Okay you may say, but there is an obvious risk that there will be clashes if people just wildly assign public ids…

Right so, but as long as all users generate random cryptographic keys, there is just an absolutely miniscule risk that the clash will go undetected.

Consider that ten different users have given their keys the public id 0001 (seems pretty likely that something like that could happen). Now, assume that all have assigned keys to them which are k1, k2, k3…k10. If an user from realm 10 tries to logon realm 5, the decryption will create some form of garbage and most likely, the CRC16 won’t match. But there is a 1 / 2^16 probability after all. But, the private ID will then not match with 1 / 2^48 risk of a clash.

Assigning proper cryptographic keys is a deep topic of its own and I won’t go into that. For most practical purposes however, just using pseudo-random numbers generated with a reasonably clever seed is often enough.

The private id is a fixed 6-bytes string. There are three basic principles how to use it:

a) Assign a fixed value, such as 00 00 00 00 00 00 shared for all keys. When the OTP is decrypted, this field is verified to be this fixed string. In order add some more randomness, use a random value rather than just zeroes.

b) Give each key a unique and randomized number.

c) Use the field to store a unique identity that has a meaning for your organization, such as an employee-id. By having the relevant number here, less information is revealed for anyone snooping on OTPs.


Hope this short primer helps and answers your questions.

Regards,

JakobE
Hardware- and firmware guy @ Yubico

The source code at http://code.google.com/p/yubico-usb-win32/
does not include the COM object source. Is the libUSB implementation equivalently functional already?

We noticed the binary COM object cannot program a yubikey on Vista, so we started wondering whether the code could be improved or extended.

Just wondering what the feature parity is between the binary and the libusb source code, which seem to be completely separate projects.

It seems like there is a Vista specific issue with the programming API.

I certainly feel a bit shameful for not having tested it on Vista at all - although I'm a low-level Windows guy by breed, I've just ignored Vista and cleaned it out from all new computers nearby.

I will immediately start investigating this issue and return with an update.

When it is fixed, we'll publish the source as well.

Regards,

Jakob E
Hardware- and firmware guy @ Yubico

That is good news, thank you for the update.

Maybe that could be like the Java convention that uses a domain name (or hash thereof)

You can get high-quality password from here: https://www.grc.com/passwords.htm
Just copy-paste from that page -- You can see algorithm used by reading the same page.