Docs: How to generate plugin-compatible keys externally

[sterlind]

Why did you need to do this?

I couldn't use age-plugin-yubikey for key generation. My Yubikey has a custom management key (not supported), and it's AES192 (also not supported.) However, I was able to generate a key on my own using ykman directly.

How?

1. Generate the key-pair:

ykman piv keys generate -P <pin text> -a ECCP256 --pin-policy NEVER --touch-policy NEVER -m <management key hex> 82 yk_slot_82.pub

2. Generate a self-signed cert:

ykman piv certificates generate -s CN=<user name> -m <management key hex> -P <pin text>

3. Verify that the plugin detects it:

❯ age-plugin-yubikey.exe -i --slot 1
#       Serial: <REDACTED>, Slot: 1
#         Name: CN=<REDACTED>
#      Created: Fri, 23 Jan 1969 11:11:11 +0000
#   PIN policy: Never  (A PIN is NOT required to decrypt)
# Touch policy: Never  (A physical touch is NOT required to decrypt)
#    Recipient: <REDACTED>
AGE-PLUGIN-YUBIKEY-<REDACTED>

Possible caveats

• Cert expires after one year by default (not sure if the plugin checks validity, or why it even would.)
• Plugin marks OID extensions for the PIN and touch policies. Not sure if the plugin uses those, or if it's just gravy.

Still, it'd be nice to add this to the docs, since it's not that scary.

EDIT: C# Script for Generation

Turns out age-plugin-yubikey relies on organization (O=age-plugin-yubikey) for auto-discovery, if you don't specify a slot number. I think it also does use the OID extension to read the PIN/touch policies.

Here's a C# script I hacked together which generates a compatible ECCP256 key + self-signed cert: https://gist.github.com/sterlind/1dd3bf3b61894f49025b189acfce7d09

It's very fragile - it only handles slot 0x82, sets hard-coded policies, etc. - but this was the lesser evil for me.

[nwf]

FWIW, you can set the extensions using openssl, too, using its PKCS11 engine, thus:

1. Have the Yubikey generate a CSR:

   ykman piv certificates request -P ${pinText} -s CN=${keyname}/O=age-plugin-yubikey 82 yk_slot_82.pub yk_slot_82.csr
   

2. Have the Yubikey sign that CSR with the extensions in place, using the YKCS11 PKCS#11 module. The values for the id= component of the -signkey URI are as per https://docs.yubico.com/software/yubikey/tools/pivtool/piv-tool-ykcs11.html#key-mapping . The two bytes in the extension value (DER:...) are the pin then touch policies, encoded as per the plugin's util.rs which is as somewhat lightly documented by yubico.

   PKCS11_MODULE_PATH=/.../libykcs11.so \
     openssl x509 -req -days 356 -extfile <(echo 1.3.6.1.4.1.41482.3.8 = DER:01:01)  \
      -signkey "org.openssl.engine:pkcs11:pkcs11:id=%05" \
      -in ./yk_slot_82.csr -out ./yk_slot_82.crt
   

3. Send that certificate over to the Yubikey:

   ykman piv certificates import 82 ./yk_slot_82.crt
   

4. Optionally, read it back:

   ykman piv certificates export 82 - | openssl x509 -noout -text -certopt ext_dump
   

It'd also have been quite nice to know how to generate the recipient string given the public key, so that everything needed for, say, an agenix setup can be computed without the use of the plugin itself being available on the machine doing the Yubikey preparation. Computing the bech32 encoding of the SECP256R1 compressed representation of the public key is moderately unpleasant; bech32 is moderately niche and openssl's myriad of tools are loathe to reveal raw key material without mangling it for pretty printing in one way or another. I haven't found a more concise way to mangle one into the other than this ugly bit of Python that wraps the bech32 reference implementation, segwit_addr:

import cryptography.hazmat.primitives.serialization as cs
import cryptography.hazmat.primitives.asymmetric.ec as cae
import segwit_addr as sw
import sys

key = cs.load_pem_public_key(sys.stdin.read().encode("ascii"))
assert isinstance(key, cae.EllipticCurvePublicKey)
assert isinstance(key.curve, cae.SECP256R1)
print(sw.bech32_encode("age1yubikey",
  sw.convertbits(
    key.public_bytes(cs.Encoding.X962, cs.PublicFormat.CompressedPoint),
    8, 5),
  sw.Encoding.BECH32))

Replace "age1yubikey" with "age1tag" for age 1.3 and once #213 lands.

Phew!