[openpgp] Re: HKP draft TODO items

--===============9099798602038924331==
Content-Type: multipart/alternative; boundary="00000000000076735906527369ba"

--00000000000076735906527369ba
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

Hello Andrew,

Thank you for laying out the TODO items, and congratulations on adoption of
the draft as a WG item.

A few comments, mostly from an implementer-facing readability and
testability perspective:

   1. Split version from fingerprint with a path separator

I support this change. It makes the boundary between the version octet and
the fingerprint unambiguous, and it is easier to explain and test than a
concatenated vfingerprint value.

It may be worth specifying the parsing rules tightly enough for negative
tests, for example:

   - the version path component is exactly two hexadecimal characters
   representing the key version octet;
   - the fingerprint path component is hexadecimal notation without a 0x
   prefix;
   - hex case is accepted case-insensitively, unless the draft wants to
   require a canonical lowercase form in examples only;
   - syntactically invalid components return a client error, while a
   syntactically valid but unsupported version or unknown fingerprint is
   handled as a lookup miss.


   1. Include media types in the HKP draft

I think including the media-type work in this document is reasonable if it
is scoped to the wire objects that HKP actually exchanges.

For application/pgp, I suggest making clear that the media type identifies
binary OpenPGP data, not a particular semantic grammar. Consumers still
need to parse and validate that the object is appropriate for the request
or response context.

For the update to application/pgp-keys, I suggest defining the accepted
=E2=80=9Cmixed keyring=E2=80=9D shape explicitly, for example as one or mor=
e OpenPGP
certificates together with zero or more detached revocations where the
receiving application is expected to decide how those revocations are
associated and applied. That would make the GnuPG-compatibility goal
clearer without making the media type itself imply successful validation.

   1. Legacy API status

For the Legacy API issue, I suggest adding a short statement near the start
of Section 6 along these lines:

The Legacy API is specified to document deployed HKP behavior and to
preserve interoperability with existing clients and servers.
Implementations of the v2 API are not required to implement the Legacy API
unless they claim Legacy API compatibility. Normative requirements in this
section apply only to endpoints that implement the corresponding Legacy API
operation.

That would preserve testable behavior for legacy-compatible endpoints while
avoiding the impression that new v2-only implementations are required to
support the old interface.

   1. JSON response formats

The existing field tables are useful. I would be cautious about requiring a
full JSON Schema in the main specification, because it can become another
normative artifact to keep in sync. However, it would be helpful to make
the following points explicit in one place:

   - required and optional fields for each JSON response type;
   - unknown-field handling;
   - timestamp format;
   - whether empty arrays may be omitted or must be present;
   - how human-readable rejection reasons are carried, for example through
   the existing comment field.

A non-normative JSON Schema appendix, or a test-fixture file maintained
with the draft repository, could be a good compromise for implementers.

I can help review the resulting text or prepare a small interoperability
checklist once the changes are drafted, especially around request-path
parsing, Content-Type selection, and JSON response validation.

Best regards,

Songbo Bu

On Thu, 21 May 2026 20:24:54 +0100, Andrew Gallagher
[email protected] wrote:

Hi, everyone.

Thanks for adopting the HKP draft! It has taken the scenic route, but
arrives in rude health. As I mentioned before, most of the current draft
has been implemented in hockeypuck and is live at test.pgpkeys.eu for
reference.

There are several open issues in the tracker, which can be found at
https://gitlab.com/andrewgdotcom/openpgp-hkp/-/work_items

I have marked four as =E2=80=9Cenhancement=E2=80=9D, which I believe would =
benefit from
further discussion on the list. In particular, I would like to make two
substantive changes right away:

   1. Split version from fingerprint with path separator

The current way that a version-tagged fingerprint is included in the v2
request URI has some undesirable side-effects that can result in user
confusion. I feel it is better if the version and the fingerprint were
separated by a path separator, so instead of:

/pks/v2/certs/by-vfingerprint/06deadbeefdeadbeef=E2=80=A6

we would use:

/pks/v2/certs/by-vfingerprint/06/deadbeefdeadbeef=E2=80=A6

I think this improves the clarity of the v2 API, and would benefit both
implementers and users. If there are no objections, I will update the
draft and the reference implementation.

(https://gitlab.com/andrewgdotcom/openpgp-hkp/-/work_items/52)

   1. Include media types in HKP draft

I previously proposed a (now-expired) OpenPGP Media Types draft, which
would have defined multiple new media types (MIME types) for binary and
ASCII-armored OpenPGP wire formats that aren=E2=80=99t covered by the types
specified in RFC3156.

I have since been persuaded that the easiest path forward is:

a) define a single new media type, application/pgp, to cover all
binary OpenPGP data, regardless of grammar.

b) update the existing application/pgp-keys type to permit =E2=80=9Cmixed
keyrings=E2=80=9D, i.e. certificates with zero or more prefixed =E2=80=9Cde=
tached
revocations=E2=80=9D, for backwards compatibility with GnuPG.

c) do so in draft-ietf-openpgp-hkp, rather than a separate draft.

d) leave the other ASCII-armored formats alone at this time.

This is based on the assumption that application/pgp (binary format)
will be the standard media type used by modern applications, and that
ASCII armor is a legacy format for compatibility with specific 7-bit
clean applications (such as email).

If this is agreeable to the group, I will draw up some language.

(https://gitlab.com/andrewgdotcom/openpgp-hkp/-/work_items/53)

The other two =E2=80=9Cenhancements=E2=80=9D were raised earlier by Michael=
 during the
adoption discussion:

   -

   =E2=80=9Cmore clearly document that the Legacy API
   is non-normative, informational=E2=80=9D
   (https://gitlab.com/andrewgdotcom/openpgp-hkp/-/work_items/44)
   -

   =E2=80=9CMore formal specification of JSON response formats=E2=80=9D
   (https://gitlab.com/andrewgdotcom/openpgp-hkp/-/work_items/48)

Suggestions for specific language, or how to otherwise resolve these
questions are welcome.
Lower-priority items

Some of the remaining items are marked =E2=80=9Cfixup=E2=80=9D, including m=
any of
Michael=E2=80=99s other suggestions, and I feel these are uncontroversial. =
I
will work on them in the background and let the working group know when
any changes are ready.

Some are marked =E2=80=9Copen question=E2=80=9D, where I am unsure how (or =
if) to
proceed. Discussion on these items is welcome, but not strictly necessary.

The rest are marked =E2=80=9Cwishlist=E2=80=9D, and may not be necessary at=
 this or any
stage, but if anyone has an opinion please speak up, either here or on
the individual tickets.

Thanks,
Andrew.

--00000000000076735906527369ba
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><p>Hello Andrew,</p>
<p>Thank you for laying out the TODO items, and congratulations on adoption=
 of the draft as a WG item.</p>
<p>A few comments, mostly from an implementer-facing readability and testab=
ility perspective:</p>
<ol>
<li>Split version from fingerprint with a path separator</li>
</ol>
<p>I support this change. It makes the boundary between the version octet a=
nd the fingerprint unambiguous, and it is easier to explain and test than a=
 concatenated vfingerprint value.</p>
<p>It may be worth specifying the parsing rules tightly enough for negative=
 tests, for example:</p>
<ul>
<li>the version path component is exactly two hexadecimal characters repres=
enting the key version octet;</li>
<li>the fingerprint path component is hexadecimal notation without a 0x pre=
fix;</li>
<li>hex case is accepted case-insensitively, unless the draft wants to requ=
ire a canonical lowercase form in examples only;</li>
<li>syntactically invalid components return a client error, while a syntact=
ically valid but unsupported version or unknown fingerprint is handled as a=
 lookup miss.</li>
</ul>
<ol>
<li>Include media types in the HKP draft</li>
</ol>
<p>I think including the media-type work in this document is reasonable if =
it is scoped to the wire objects that HKP actually exchanges.</p>
<p>For <code>application/pgp</code>, I suggest making clear that the media =
type identifies binary OpenPGP data, not a particular semantic grammar. Con=
sumers still need to parse and validate that the object is appropriate for =
the request or response context.</p>
<p>For the update to <code>application/pgp-keys</code>, I suggest defining =
the accepted =E2=80=9Cmixed keyring=E2=80=9D shape explicitly, for example =
as one or more OpenPGP certificates together with zero or more detached rev=
ocations where the receiving application is expected to decide how those re=
vocations are associated and applied. That would make the GnuPG-compatibili=
ty goal clearer without making the media type itself imply successful valid=
ation.</p>
<ol>
<li>Legacy API status</li>
</ol>
<p>For the Legacy API issue, I suggest adding a short statement near the st=
art of Section 6 along these lines:</p>
<blockquote>
<p>The Legacy API is specified to document deployed HKP behavior and to pre=
serve interoperability with existing clients and servers. Implementations o=
f the v2 API are not required to implement the Legacy API unless they claim=
 Legacy API compatibility. Normative requirements in this section apply onl=
y to endpoints that implement the corresponding Legacy API operation.</p>
</blockquote>
<p>That would preserve testable behavior for legacy-compatible endpoints wh=
ile avoiding the impression that new v2-only implementations are required t=
o support the old interface.</p>
<ol>
<li>JSON response formats</li>
</ol>
<p>The existing field tables are useful. I would be cautious about requirin=
g a full JSON Schema in the main specification, because it can become anoth=
er normative artifact to keep in sync. However, it would be helpful to make=
 the following points explicit in one place:</p>
<ul>
<li>required and optional fields for each JSON response type;</li>
<li>unknown-field handling;</li>
<li>timestamp format;</li>
<li>whether empty arrays may be omitted or must be present;</li>
<li>how human-readable rejection reasons are carried, for example through t=
he existing <code>comment</code> field.</li>
</ul>
<p>A non-normative JSON Schema appendix, or a test-fixture file maintained =
with the draft repository, could be a good compromise for implementers.</p>
<p>I can help review the resulting text or prepare a small interoperability=
 checklist once the changes are drafted, especially around request-path par=
sing, Content-Type selection, and JSON response validation.</p>
<p>Best regards,</p>
<p>Songbo Bu</p>
<p>On Thu, 21 May 2026 20:24:54 +0100, Andrew Gallagher <a href=3D"mailto:a=
[email protected]" target=3D"_blank">andrewg=3D40andrew=
[email protected]</a> wrote:</p>
<blockquote>
<p>Hi, everyone.</p>
<p>Thanks for adopting the HKP draft! It has taken the scenic route, but<br=
>
arrives in rude health. As I mentioned before, most of the current draft<br=
>
has been implemented in hockeypuck and is live at <a href=3D"http://test.pg=
pkeys.eu" target=3D"_blank">test.pgpkeys.eu</a> for<br>
reference.</p>
<p>There are several open issues in the tracker, which can be found at<br>
<a href=3D"https://gitlab.com/andrewgdotcom/openpgp-hkp/-/work_items" targe=
t=3D"_blank">https://gitlab.com/andrewgdotcom/openpgp-hkp/-/work_items</a><=
/p>
<p>I have marked four as =E2=80=9Cenhancement=E2=80=9D, which I believe wou=
ld benefit from<br>
further discussion on the list. In particular, I would like to make two<br>
substantive changes right away:</p>
<ol>
<li>Split version from fingerprint with path separator</li>
</ol>
<p>The current way that a version-tagged fingerprint is included in the v2<=
br>
request URI has some undesirable side-effects that can result in user<br>
confusion. I feel it is better if the version and the fingerprint were<br>
separated by a path separator, so instead of:</p>
<p>/pks/v2/certs/by-vfingerprint/06deadbeefdeadbeef=E2=80=A6</p>
<p>we would use:</p>
<p>/pks/v2/certs/by-vfingerprint/06/deadbeefdeadbeef=E2=80=A6</p>
<p>I think this improves the clarity of the v2 API, and would benefit both<=
br>
implementers and users. If there are no objections, I will update the<br>
draft and the reference implementation.</p>
<p>(<a href=3D"https://gitlab.com/andrewgdotcom/openpgp-hkp/-/work_items/52=
" target=3D"_blank">https://gitlab.com/andrewgdotcom/openpgp-hkp/-/work_ite=
ms/52</a>)</p>
<ol>
<li>Include media types in HKP draft</li>
</ol>
<p>I previously proposed a (now-expired) OpenPGP Media Types draft, which<b=
r>
would have defined multiple new media types (MIME types) for binary and<br>
ASCII-armored OpenPGP wire formats that aren=E2=80=99t covered by the types=
<br>
specified in RFC3156.</p>
<p>I have since been persuaded that the easiest path forward is:</p>
<p>a) define a single new media type, <code>application/pgp</code>, to cove=
r all<br>
binary OpenPGP data, regardless of grammar.</p>
<p>b) update the existing <code>application/pgp-keys</code> type to permit =
=E2=80=9Cmixed<br>
keyrings=E2=80=9D, i.e. certificates with zero or more prefixed =E2=80=9Cde=
tached<br>
revocations=E2=80=9D, for backwards compatibility with GnuPG.</p>
<p>c) do so in draft-ietf-openpgp-hkp, rather than a separate draft.</p>
<p>d) leave the other ASCII-armored formats alone at this time.</p>
<p>This is based on the assumption that <code>application/pgp</code> (binar=
y format)<br>
will be the standard media type used by modern applications, and that<br>
ASCII armor is a legacy format for compatibility with specific 7-bit<br>
clean applications (such as email).</p>
<p>If this is agreeable to the group, I will draw up some language.</p>
<p>(<a href=3D"https://gitlab.com/andrewgdotcom/openpgp-hkp/-/work_items/53=
" target=3D"_blank">https://gitlab.com/andrewgdotcom/openpgp-hkp/-/work_ite=
ms/53</a>)</p>
<p>The other two =E2=80=9Cenhancements=E2=80=9D were raised earlier by Mich=
ael during the<br>
adoption discussion:</p>
<ul>
<li>
<p>=E2=80=9Cmore clearly document that the Legacy API<br>
is non-normative, informational=E2=80=9D<br>
(<a href=3D"https://gitlab.com/andrewgdotcom/openpgp-hkp/-/work_items/44" t=
arget=3D"_blank">https://gitlab.com/andrewgdotcom/openpgp-hkp/-/work_items/=
44</a>)</p>
</li>
<li>
<p>=E2=80=9CMore formal specification of JSON response formats=E2=80=9D<br>
(<a href=3D"https://gitlab.com/andrewgdotcom/openpgp-hkp/-/work_items/48" t=
arget=3D"_blank">https://gitlab.com/andrewgdotcom/openpgp-hkp/-/work_items/=
48</a>)</p>
</li>
</ul>
<p>Suggestions for specific language, or how to otherwise resolve these<br>
questions are welcome.</p>

Lower-priority items
<p>Some of the remaining items are marked =E2=80=9Cfixup=E2=80=9D, includin=
g many of<br>
Michael=E2=80=99s other suggestions, and I feel these are uncontroversial. =
I<br>
will work on them in the background and let the working group know when<br>
any changes are ready.</p>
<p>Some are marked =E2=80=9Copen question=E2=80=9D, where I am unsure how (=
or if) to<br>
proceed. Discussion on these items is welcome, but not strictly necessary.<=
/p>
<p>The rest are marked =E2=80=9Cwishlist=E2=80=9D, and may not be necessary=
 at this or any<br>
stage, but if anyone has an opinion please speak up, either here or on<br>
the individual tickets.</p>
<p>Thanks,<br>
Andrew.</p>
</blockquote>
</div>

--00000000000076735906527369ba--


--===============9099798602038924331==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: base64
Content-Disposition: inline

X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX18Kb3BlbnBncCBt
YWlsaW5nIGxpc3QgLS0gb3BlbnBncEBpZXRmLm9yZwpUbyB1bnN1YnNjcmliZSBzZW5kIGFuIGVt
YWlsIHRvIG9wZW5wZ3AtbGVhdmVAaWV0Zi5vcmcK

--===============9099798602038924331==--