Yubico Forum

Dear Yubico team,

I have recently acquired my first Yubikey and I am still getting to grips with it. I would consider my personal computer literacy to be significantly above average.

Despite this, I am finding the Yubikey to be a frustrating product to figure out. I have had quite a few frustrating experiences with it, pretty much all of which boil down to very poor documentation.
My experience of the documentation provided on the website itself is that it's difficult to find, scattered around multiple pages, and from the way the documentation is written it seems clear that the person who wrote it has very well grounded knowledge of the product.
That last comment is not a compliment, as documentation should be written from the perspective of someone who doesn't know how to use it, not from the perspective of a person who does know how to use it.

To elaborate on this, I'll give a couple of examples.

First, when I received my Yubikey, I decided to install the software for it. From the website front page I discover SUPPORT->DOWNLOADS.

At the Downloads page I am presented with a plethora of software to download:

Yubico Authenticator
Yubico Neo Manager
Yubico Personalisation Tool (preferred)
Yubico Personalization Tool (command line interface)
Yubikey PIV Manager
Yubikey PIV Tool
Yubikey for SF
YubiHSM

Well, which one should I install to get started? The programs are presented but none of them are explained. I bought the Neo so naturally I'd think I need the Yubico Neo Manager, but actually I later discovered that I needed the Yubico Personalisation tool. To get that, I need to download the source and install a bunch of dependencies etc. Which OK, I did it, but I can imagine a complete beginner being confronted with this and thinking... what the heck?

A second example: I tried to create a PGP key and copy it to my Yubikey, following the instructions here:
https://developers.yubico.com/PGP/Importing_keys.html

The Pre-requisites say: The version of the YubiKey’s OpenPGP module must be 1.0.5 or later.

Well, what does that mean? It isn't explained. Is it some software I'm supposed to download? Who knows.

I move on and complete the rest of the instructions in the documentation. Right at the very end, when trying to copy the key to the card, I get an error:



Then, much later on, I discover a separate page elsewhere on the Yubico site which explains that the OpenPGP applet is disabled on the Yubikey neo! You have to enable it, but you can't do it with the GUI personalisation tool you have to use the command line tool. Why?
So I start looking into that and I find some more information, again elsewhere, which claims that using the command line tool will overwrite a bunch of things on the Yubikey.

So that particular problem is not resolved for me yet as I don't really know what's supposed to go on here.



Anyway, even though my comments on this might sound very negative, I mean them constructively. I think that documentation is very poor. And, even though the Yubikey is probably not targetted at general computer users (if it is, they don't have a hope in my opinion!), I still think there is a lot of room for improvement here.

I checked the videos on the website: very poor. They are very short basic videos showing what you can do with the Yubikey, but not really *how* to do it.

It would be great if there was one place on the website that people can go to and find all the information they need when getting started with plenty of examples of how to set the Yubikey up to complete various authentication tasks.

I found myself somewhat lost when I started as well. I didn't have a good orientation until I had walked through all of the web set topics and the (slightly out of date) user manual at https://www.yubico.com/wp-content/uploa ... l_v3.4.pdf (found on the support->documentation page https://www.yubico.com/support/documentation/)

I think the problem is that what a Yubikey is has evolved over the years, and a lot of the documents are written either in the historical order or assuming that you are already familiar with the history. The names of the tools don't help so much either.

Here is my take (someone will hopefully correct me if I'm wrong; I'm still new to this space myself)

1) Back in the day, Yubikey was a One Time Password generator that acted like a keyboard. It had 2 slots of memory. It is configured with the Personalization Tool (GUI or CLI), and supports YubicoOTP, HOTP, TOTP, static passwords, etc. Lots of nifty features, some added to later versions of the product

2) Then, they introduced NEO, which had the functionality of the original Yubikey but adds Smart Card functions (not really mentioned in the manual until chapter 7!). The Smart Card functionality adds more OTP slots for HOTP/TOTP (but not in keyboard emulation), has a PIVCard app, and an OpenPGP app. It also supports U2F. The original OTP, the smart card, and the U2F are 3 functions that can be enabled or disabled independently. Some keys only have the keyboard OTP enabled by default. Others have all by default.

3) Yubikey4 is the most recent. Unlike NEO, it doesn't have NFC, but does support larger OpenPGP keys and more Smart Card based OTP slots, and some new features (like requiring presence confirmation for operations). Like the neo, the neoman tool can be used to configure most of the modes.


You mention not knowing where to get started. This is indeed a problem; the device has so many functions that it is difficult to guess someone's use-case. An overview page near the beginning would be helpful (something like the diagram at the bottom of page 3 of https://www.yubico.com/wp-content/uploa ... tSheet.pdf), with a breakout.

E.G.
* Want to Enable/Disable components: neoman (neo/yubikey4 and later)
* Want to configure OTPs typed for you? Yubico Personalization Tool
* Want to configure x509 certificates for PIV-Card? pivman or pivtool
* Want to configure OpenPGP keys? gpg2/pscd
* Want to configure many HOTP or TOTP? Yubico Authenticator
* Want to use U2F? page about browser support and mentioning neoman to ensure enabled, possibly linking to other info like PAM modules


For each, a link on how to install (recommending the repositories of prebuilt binaries) would probably be helpful. They could all point to the same page since the software installation instructions are about the same.

Thanks very much for the detailed response linsam!

I am still struggling with my Yubikey but the information you've provided has helped my overall understanding of the situation.

The whole encryption thing is a complete mess. Apple did it right on the iPhone because no one is even aware of it until someone needs to crack into it. It just works.

I like the cool factor of my Yubi keys, but using it requires too much effort. Ideally, I'd love to see more Google/Github/Dropbox-like implementations; and where the hell are the banks? The Yubikey Neo would be an ideal device for authenticating credit card transaction, in person and online. It's not a documentation problem, but rather an issue with implementation. Same is true with PGP---I use it, but no one else does.

For this to work, we need seamless integration with what we already use. The geeks will figure out the cool stuff, but the rest of us just want this device to work protecting our cloud, finances, and computing devices.

I am afraid that someone besides Yubico is going to figure this out first, and they'll profit nicely.

This thread is worthy of a bump; getting a self-hosted OTP validation server working in a test environment has been challenging, because the Yubico documentation for the various services isn't linked together properly, or for example, recommends the use of a YubiHSM at the start of a document, and then proceeds to setup an environment *without a YubiHSM*...

https://developers.yubico.com/OTP/Guide ... ation.html

"You can optionally use a YubiHSM USB device to keep these secret values secure, even in the event of a KSM server becoming compromised. Due to the increased safety gained by using a YubiHSM, this is the approach we recommend."

"Now, as we will not be using a YubiHSM for in this guide, we need to create a master key for encrypting Now we need to create a master key for decrypting Yubico OTP secrets with, and since we will not be using a YubiHSM in this guide, we do so by creating a plaintext file:" (plus typo: 'encrypting Now we need to')

Argh.

Another one might be the pam_yubico man page; further syntax examples of some of the attributes would be useful, especially when dealing with LDAP lookups. yubi_attr, yubi_attr_prefix come to mind.

https://developers.yubico.com/yubico-pa ... ico.8.html

A sample attribute definition / objectClass might also be handy. This person has published one that seems reasonable, but what does Yubico recommend these days?

http://logix.cz/michal/devel/yubikey-ldap/

I wonder if converting the Yubico documentation to a wiki format would be useful, so folks could at least document success / failure somewhere useful?