search

str4d / rage

A simple, secure and modern file encryption tool (and Rust library) with small explicit keys, no config options, and UNIX-style composability.
https://age-encryption.org/v1
Apache License 2.0
2.69k stars 104 forks source link

UX: README incorrectly implies that age-plugin-yubikey broadly supports PIV tokens #541

Open RespiteSage opened 1 month ago

RespiteSage commented 1 month ago

The rage README file says that

Hardware PIV tokens such as YubiKeys are supported through the age-plugin-yubikey plugin.

but age-plugin-yubikey only supports a particular subset of PIV tokens (per this issue, P256 tokens in the 20 "retired" slots).

This isn't a huge issue, but clarifying the language might save someone else the time it took me to try out age-plugin-yubikey and look through issues before I found the issue linked above.

I think something like

Some PIV tokens, including YubiKeys, are supported through the age-plugin-yubikey plugin.

would be enough of a change.

I've also created a discussion in the age repo, so if that makes this issue redundant (e.g. because changes to the age README would likely result in similar changes to the rage README), feel free to close it.

str4d commented 1 month ago

The rage README file says that

Hardware PIV tokens such as YubiKeys are supported through the age-plugin-yubikey plugin.

but age-plugin-yubikey only supports a particular subset of PIV tokens (per this issue, P256 tokens in the 20 "retired" slots).

The keys stored on YubiKeys are not "tokens". P256 in the context of PIV refers to an algorithm for which keys can be generated, and the 20 "retired" slots are another part of the PIV specification (places where key material can be stored). Indeed in age-plugin-yubikey I only support P256, because the only two options when I wrote the plugin were P256 and RSA, and I had no intention of supporting the latter. (Newer YubiKey firmwares have Curve25519 support, which means I can also add native age key support once I have access to one of these newer YubiKeys: https://github.com/str4d/age-plugin-yubikey/issues/174).

"Token" here means the hardware device itself. The language comes from the various PIV standards. For example, in NIST SP 800-57) section 1.5.1 Glossary:

Token A portable, user-controlled, physical device (e.g., smart card or memory stick) used to store cryptographic information and possibly also perform cryptographic functions.

So the documentation is correct that "hardware PIV tokens such as YubiKeys are supported". More specifically, in the age-plugin-yubikey README I state:

Manual setup and technical details

age-plugin-yubikey only officially supports the following YubiKey variants, set up either via the text interface or the --generate flag:

  • YubiKey 4 series
  • YubiKey 5 series

NOTE: Nano and USB-C variants of the above are also supported. The pre-YK4 YubiKey NEO series is NOT supported. The blue "Security Key by Yubico" will also not work (as it doesn't support PIV).

In practice, any PIV token with an ECDSA P-256 key and certificate in one of the 20 "retired" slots should work. You can list all age-compatible keys with:

$ age-plugin-yubikey --list-all

If there's another phrase I could add besides "PIV token" that might make this even clearer, I could do so.

RespiteSage commented 1 month ago

Thank you for the correction about my language ("token" meaning the hardware device rather than the keys).

I think there may be a disconnect between what you intended to communicate when writing that line in the readme and what I understood when I read it. Your intended reading of

Hardware PIV tokens such as YubiKeys are supported through ...

might be

There exist hardware PIV tokens (for example, Yubikeys) which are supported through ...

but the reading that feels natural to me (i.e. what I believed it to mean) is

Hardware PIV tokens generally (for example, Yubikeys) are supported through ...

with the normal OSS understanding that support is best-effort and possibly not comprehensive. However, age-plugin-yubikey is explicitly not intended to provide broad support for PIV token usage (per the linked issue).

Perhaps I should have avoided the word "incorrect" in the title of this issue, but the only more accurate description I can think of is "misleading" which has an implication of purposeful deception that I wanted to avoid.

In any case, I think a slight rewording would be useful to anyone like me who arrived at the age and rage repos hoping to utilize keys on their PIV tokens which age-plugin-yubikey in not intended to support.

Examples:

Some hardware PIV tokens such as YubiKeys are supported through ...

Many hardware PIV tokens such as YubiKeys are supported through ...

Hardware PIV tokens with compatible keys such as YubiKeys are supported through ...

I also want to mention that I didn't open any issues in age-plugin-yubikey because the readme in that project is clear about the intended scope of the project. I would just like the readme files for rage and age to no longer seem (to me) to contradict the readme for age-plugin-yubikey, since it caused me confusion which could easily be avoided for others.