doc: write about multiple recipients

README.md

@@ -98,6 +98,53 @@ hardware, you can set the environment variable `AGE_TKEY_PORT` to
 QEMU's char-device (shown when QEMU starts up). Before running `age`,
 do something like `export AGE_TKEY_PORT=/dev/pts/22`.
 
+### Multiple recipients
+
+Files encrypted for multiple recipients are indeed handled by this
+plugin. There is however one gotcha which might be slightly confusing
+and annoying at times. If your TKey identity requires touch (which
+they do by default), then you may have to touch your TKey more than
+one time when decrypting a single piece of data that has been
+encrypted for more than one recipient.
+
+The best you can do to avoid this when encrypting for multiple
+recipients using `age` is to pass any TKey recipient with the *first*
+`-r`. Also, when decrypting, if the identity file you're passing with
+`-i` has multiple identities, then make sure any TKey identity line
+comes last. This will avoid "unnecessary" touching if the data can be
+decrypted using an earlier non-TKey identity. Below follows a more
+in-depth explanation.
+
+Recipients for identities based in TKey have the same format as
+recipients for identities generated by the native `age-keygen`. This
+ought to be because TKey also use native X25519 keys.
+
+The consequence is that when you are decrypting using a TKey identity
+(`-i`) and the data is encrypted for multiple recipients, then an
+attempt to use the TKey (for ECDH) will be made for each native X25519
+recipient, in the order they were passed with `-r` -- but I guess
+implementations could vary. Imagine some data encrypted and then
+decrypted like this:
+
+```
+age-keygen -o some-agekeygen-id
+# Note the RECIPIENT (public key) for this some-agekeygen-id
+
+age-plugin-tkey --generate -o my-tkey-id
+# Note the RECIPIENT (public key) for this my-tkey-id
+
+printf "some data\n" | age -r SOME-AGEKEYGEN-RECIPIENT -r MY-TKEY-RECIPIENT --encrypt -o ./ciphertext
+
+age -i my-tkey-id --decrypt ./ciphertext
+```
+
+When decrypting, two recipients are found to be native X25519, so both
+will have to be tried using the TKey identity (`-i`). The first
+recipient (non-TKey) passed using `-r` will be tried first. You will
+have to touch your TKey, but decryption will fail silently. Then the
+second recipient (TKey) will be tried. You will have to touch TKey
+again, but this time decryption will succeed.
+
 ## Building
 
 For ease of installing and building the `age-plugin-tkey` Go program, we

tests/test2.sh

@@ -27,7 +27,8 @@ if [[ -z "$r_tkey" ]] || [[ -z "$r_age" ]]; then
 fi
 
 plaintext="too many secrets"
-printf "%s" "$plaintext" | age -e -r "$r_age" -r "$r_tkey" -o out/test2-ciphertext-both
+# encrypting with the tkey-recipient first, avoiding having to touch 2 times
+printf "%s" "$plaintext" | age -e -r "$r_tkey" -r "$r_age" -o out/test2-ciphertext-both
 
 cat <<EOF
 
@@ -46,15 +47,6 @@ age -d -i out/test2-id-tkey-only <out/test2-ciphertext-both
 
 # Should decrypt, no matter any TKey
 age -d -i out/test2-id-age-only <out/test2-ciphertext-both
-
-# If you ran test2.sh --touch and try to decrypt with the TKey
-# identity, then you have to touch the TKey 2 times. Could this be
-# because recipients for age-plugin-tkey identities look just like the
-# age native recipients? Because it has an ed25519 pubkey. So both
-# have to be tried by the plugin? Hm, but adding a 3rd (age native)
-# identity to encrypt for does not result in the need for touch 3
-# times... (TODO).
-
 EOF
 
 exit 0