age-piv-p256 recipient stanza by remko · Pull Request #31 · C2SP/C2SP

remko · 2023-05-10T18:58:47Z

This is an initial draft of a specification for the age piv-p256 recipient stanza, as used by age-plugin-yubikey and age-plugin-se.

remko · 2023-05-10T18:59:34Z

age-piv-p256.md

+2.  The second argument is the base-64 encdoded tag of the recipient,
+    consisting of the first 4 bytes of the SHA-256 hash of the
+    recipient:
+
+         tag = SHA-256(recipient)[0..4]


I was wondering if the tag should be salted, to hide relations between stanzas (in different files) for the same recipient and/or anonymize the recipient

Hmm what do you have in mind?

Maybe x = CSPRNG(4); tag = x || HMAC(recipient, x)[0..4] so that only someone who knows the recipient can link files?

That is indeed a nice step forward in privacy! Might be worth making a backwards-incompatible change. @str4d, what do you think?

I think it's pretty common to just use the x-coordinate, similar to X25519

I think it's pretty common to just use the x-coordinate, similar to X25519

For the shared ECDH output yes, but the input is usually either a compressed or an uncompressed point, no? x-coordinate-only ECDH like in X25519 is very uncommon on P-256. (I recently surveyed a bunch of ECDH and ECIES implementations while designing the crypto/ecdh.)

Which spec uses a SEC1-encoded point as the input?

TLS 1.3 (by way of IEEE1363) uses the x-coordinate, for example:

https://datatracker.ietf.org/doc/html/rfc8446#section-7.4.2

7.4.2. Elliptic Curve Diffie-Hellman

For secp256r1, secp384r1, and secp521r1, ECDH calculations (including
parameter and key generation as well as the shared secret
calculation) are performed according to [IEEE1363] using the
ECKAS-DH1 scheme with the identity map as the key derivation function
(KDF), so that the shared secret is the x-coordinate of the ECDH
shared secret elliptic curve point represented as an octet string.

My bad, I was originally trying to reply to this comment

Maybe x = CSPRNG(4); tag = x || HMAC(recipient, x)[0..4] so that only someone who knows the recipient can link files?

That's indeed what I had in mind, except I was thinking of putting x in a separate stanza argument instead of concatenating it (to avoid a custom split)

Is there a reason to prefer this construction instead of HMAC(recipient, ephemeral share)[0..4]?

IANAC, but sounds nice and simple to me.

FiloSottile · 2023-08-25T09:35:51Z

age-piv-p256.md

+If the shared secret is all 0x00 bytes, the identity implementation MUST
+abort.


Suggested change

If the shared secret is all 0x00 bytes, the identity implementation MUST

abort.

If the shared secret is the point at infinity, the identity implementation

MUST abort.

The infinity is going to be represented differently by different libraries, and often not as a long string of 0x00.

FiloSottile · 2023-08-25T09:38:17Z

age-piv-p256.md

+    salt = ephemeral share || recipient
+    info = "piv-p256"
+    shared secret = P256(ephemeral secret, recipient)
+    wrap key = HKDF-SHA-256(ikm = shared secret, salt, info)


If we make other backward-incompatible changes, we should swap salt and info here. HKDF is... very theoretically documented, and this is a mistake I made in the original design. It doesn't have practical consequences, and I think one can prove the security of the current design, but it makes applying more sophisticated proofs annoying.

FiloSottile · 2023-08-25T09:40:31Z

age-piv-p256.md

+    the recipient implementation as follows:
+
+         ephemeral secret = read(CSPRNG, 32)
+         ephemeral share = P256(ephemeral secret, basepoint)


"P256" is not a well-defined ECDH operation the way X25519 is.

We should define it somewhere as scalar multiplication over P-256, with SEC 1 point decoding and encoding. (Assuming that's what we are doing? But then why is the third argument 32 bytes?)

My comments about using the x-coordinate for ECDH with P-256 (and really all the NIST P-curves) were supposed to be in reply to this comment. I guess I must've clicked the wrong one in my previous replies.

Replying to #31 (comment).

The ECDH output is the x-coordinate. The ECDH input (that is, the third stanza argument here) is 0x04 || x || y, which is SEC 1.

https://datatracker.ietf.org/doc/html/rfc8446#section-4.2.8.2

FiloSottile · 2023-08-25T09:43:11Z

age-piv-p256.md

+2.  The second argument is the base-64 encdoded tag of the recipient,
+    consisting of the first 4 bytes of the SHA-256 hash of the
+    recipient:
+
+         tag = SHA-256(recipient)[0..4]


Hmm what do you have in mind?

Maybe x = CSPRNG(4); tag = x || HMAC(recipient, x)[0..4] so that only someone who knows the recipient can link files?

That is indeed a nice step forward in privacy! Might be worth making a backwards-incompatible change. @str4d, what do you think?

FiloSottile · 2023-08-25T09:47:12Z

age-piv-p256.md

+
+## Recipient stanza
+
+A piv-p256 recipient stanza has three arguments.


If we make other changes, we should drop "piv" from the name.

Maybe tagged-p256? Or hw-p256? Or just p256?

I assume @Foxboron could use it for age-plugin-tpm, too.

I wonder if we should standardize the recipient (not identity) format, and add native support to age(1) so that one doesn't need the plugin to encrypt to PIV/TPM/SE/any other P-256 identity.

/cc @str4d

I can probably use this, I wasn't aware of this PR work when I originally wrote age-plugin-tpm.

Native support sounds neat.

You don't need to install a plugin to encrypt to these plugins. For encrypting to a different person, it feels odd that you need to install age-plugin-se even if you don't have an Apple device. It also avoids the plugin discovery problem where you need to explain which plugin people have to download to encrypt a message to you.

For age-plugin-se, I could drop all cross-platform support, since the parts that don't involve encryption are only useful on macOS. In my case, it would for example avoid all the trouble I have because my plugin is written in Swift, which doesn't support musl-based Linux systems. I can imagine there are other hardware encryption plugins that don't make sense on all platforms.

It hides information about which type of token corresponds to a certain recipient

If there's a backwards-incompatible change now, only half of the existing state machines need to be updated

Foxboron · 2024-02-16T09:37:35Z

How can we move this forward? It would be nice to have a generic implementation on the age side of things :)

I'm contemplating implementing the spec as is into age-plugin-tpm but if the naming isn't settled that would maybe be a bit annoying?

remko · 2024-02-16T16:12:28Z

How can we move this forward? It would be nice to have a generic implementation on the age side of things :)

I was hoping @str4d could give some input on the document and the change suggestions, before I started incorporating the changes (and editorial fixes).

The following backwards-incompatible changes for the recipient stanza format are on the table:

Change the tag to offer better privacy: Add randomness to the tag using either new random data or the ephemeral share.
Swap salt and info in HKDF-SHA-256

One possible way forward is to keep piv-p256 as-is, use the current version of this document (with the suggested editorial changes) as a historical description of the spec, and incorporate the changes into a different recipient format under a different recipient name (tagged-p256, hw-p256, p256), which new implementations should use.

Then there is the suggestion to standardise the recipient format and implement it in age. Age could decide to (only) implement the new recipient stanza as described above, and existing implementations then don't need to bother with implementing the encryption side of the new recipient stanza, and just need to switch to generating the new recipient when supported in age.

Foxboron · 2024-02-16T16:29:44Z

I think it would make sense to leave the current piv-p256 as-is and maybe just standardize this as p256?

FiloSottile · 2024-06-21T17:57:05Z

Thank you for getting this started. I think it's becoming clear that a standard tagged P-256 recipient type would be valuable across multiple plugins. I propose we

change the tag to HMAC(recipient, ephemeral share)[0..4];
swap HKDF salt and info;
name the new stanza p256-tag;
also specify a p256tag recipient plugin type age1p256tag1...;
implement native support for p256tag recipients in age(1) and maybe rage(1);
migrate plugins to the new stanza and recipient, but have them support decrypting the old one stanza ~forever.

Plugins might choose to provide a recipient-only age-plugin-p256tag binary for compatibility with older versions of age.

How does that sound @str4d, @Foxboron, @remko?

Foxboron · 2024-06-21T18:17:46Z

I think this sounds great!

FiloSottile · 2024-06-21T21:40:02Z

Actually, do we need a new spec for this? Why not add a section to c2sp.org/age?

Foxboron · 2024-06-21T21:48:31Z

Considering we have two other "native recipient types" I don't think a separate standard is required really. It might be nicer to ensure the age spec doesn't become super long?

remko · 2024-06-23T16:27:52Z

Actually, do we need a new spec for this? Why not add a section to c2sp.org/age?

Works for me. How do you suggest to proceed with this spec: It can be released as a 'historical' spec for documenting existing behavior of plugins, with a note forwarding to the new recipient type and recommend to implement that. Or is it not worth the trouble (and the risk of people implementing the wrong spec), and we drop it altogether, and not document anything?

remko · 2024-07-01T19:25:13Z

I propose we

FYI, the current HEAD of age-plugin-se (brew install --HEAD age-plugin-se) has an implementation of this proposal, behind a hidden --recipient-type=p256tag flag.

Foxboron · 2024-08-21T08:37:09Z

@FiloSottile are you going to propose the addition to the age spec or would it be useful if someone else finds the time to draft it?

FiloSottile · 2024-08-21T08:56:54Z

@FiloSottile are you going to propose the addition to the age spec or would it be useful if someone else finds the time to draft it?

If anyone finds the time to make a PR against the age spec, that would be awesome!

FiloSottile · 2024-08-21T08:58:06Z

How do you suggest to proceed with this spec: It can be released as a 'historical' spec for documenting existing behavior of plugins, with a note forwarding to the new recipient type and recommend to implement that. Or is it not worth the trouble (and the risk of people implementing the wrong spec), and we drop it altogether, and not document anything?

That's a good question, it would be nice for future-proofing to have the spec somewhere I guess. @C2SP/stewards how do you feel about "historical" specs?

remko · 2024-08-22T17:31:21Z

If anyone finds the time to make a PR against the age spec, that would be awesome!

The PR can be found here: #96

@remko

Based on a previous proposal by @remko, with the tag design suggested by @erincandescent. Closes #96 Closes #31

@remko

Based on a previous proposal by @remko, with the tag design suggested by @erincandescent. Closes #96 Closes #31 Co-authored-by: Jack Grigg <thestr4d@gmail.com>

@remko

Based on a previous proposal by @remko, with the tag design suggested by @erincandescent. Closes #96 Closes #31 Co-authored-by: Jack Grigg <thestr4d@gmail.com>

@remko

Based on a previous proposal by @remko, with the tag design suggested by @erincandescent. Closes #96 Closes #31 Co-authored-by: Jack Grigg <thestr4d@gmail.com>

@remko

Based on a previous proposal by @remko, with the tag design suggested by @erincandescent. Closes #96 Closes #31 Co-authored-by: Jack Grigg <thestr4d@gmail.com>

remko requested review from FiloSottile, dconnolly and str4d as code owners May 10, 2023 18:58

remko commented May 10, 2023

View reviewed changes

FiloSottile reviewed Aug 25, 2023

View reviewed changes

Foxboron mentioned this pull request Sep 12, 2023

Use the new age-piv-p256 recipient Foxboron/age-plugin-tpm#20

Closed

Foxboron mentioned this pull request Feb 16, 2024

Program fails when encrypting when there is no permission to the TPM Foxboron/age-plugin-tpm#22

Closed

remko mentioned this pull request Aug 22, 2024

age: Add specification for the p256tag recipient type & stanza. #96

Closed

remko force-pushed the age-piv-p256 branch from 4c6c0ad to 0639107 Compare August 22, 2024 18:00

age-piv-p256: Initial draft

68bde70

remko force-pushed the age-piv-p256 branch from 0639107 to 68bde70 Compare August 22, 2024 19:19

FiloSottile added a commit that referenced this pull request Aug 16, 2025

age: add tag recipient type and p256tag recipient stanza

39e3c43

Based on a previous proposal by @remko, with the tag design suggested by @erincandescent. Closes #96 Closes #31

FiloSottile closed this in 96764ad Dec 22, 2025

		If the shared secret is all 0x00 bytes, the identity implementation MUST
		abort.

-If the shared secret is all 0x00 bytes, the identity implementation MUST
-abort.
+If the shared secret is the point at infinity, the identity implementation
+MUST abort.


		## Recipient stanza

		A piv-p256 recipient stanza has three arguments.

Conversation

remko commented May 10, 2023

Uh oh!

remko May 10, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FiloSottile Aug 25, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FiloSottile Aug 25, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

remko Aug 26, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Foxboron commented Feb 16, 2024

Uh oh!

remko commented Feb 16, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Foxboron commented Feb 16, 2024

Uh oh!

FiloSottile commented Jun 21, 2024

Uh oh!

Foxboron commented Jun 21, 2024

Uh oh!

FiloSottile commented Jun 21, 2024

Uh oh!

Foxboron commented Jun 21, 2024

Uh oh!

remko commented Jun 23, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

remko commented Jul 1, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Foxboron commented Aug 21, 2024

Uh oh!

FiloSottile commented Aug 21, 2024

Uh oh!

FiloSottile commented Aug 21, 2024

Uh oh!

remko commented Aug 22, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

remko May 10, 2023 •

edited

Loading

FiloSottile Aug 25, 2023 •

edited

Loading

FiloSottile Aug 25, 2023 •

edited

Loading

remko Aug 26, 2023 •

edited

Loading

remko commented Feb 16, 2024 •

edited

Loading

remko commented Jun 23, 2024 •

edited

Loading

remko commented Jul 1, 2024 •

edited

Loading