About Keria API and HTTP Message Signatures

[psteniusubi]

About Keria API and HTTP Message Signatures

I'd like to create a "generic" API client for Keria. With dependencies to 3rd party libraries supporting crypto and http message signatures only. I don't know if this is feasible or not but I'm giving it a try.

While reviewing the HTTP Message Signature implementation of keria/signifypy I have found a couple of potential interop issues.

These are the Signature and Signature-Input headers from keria test_authing.py:

Signature: indexed="?0";signify="0BA9SX7Jyn66ZdCPOb0WqDEn1UC49GeSPypjVgeMrt6VLWKjEw9ij7Ndur7Wcrru_5eQNbSiNaiP4NQYWht5srEL"
Signature-Input: signify=("signify-resource" "@method" "@path" "signify-timestamp");created=1609459200;keyid="EJPEPKslRHD_fkug3zmoyjQ90DazQAYWI8JIrV2QXyhg";alg="ed25519"

From HTTP Message Signatures about the Signature header:

The member's key is the label that uniquely identifies the message signature within the HTTP message. The member's value is a Byte Sequence containing the signature value for the message signature identified by the label.

For better interop the key ("signify") should uniquely identify this message. The Signature header then looks like this:

Signature: signify="0BA9SX7Jyn66ZdCPOb0WqDEn1UC49GeSPypjVgeMrt6VLWKjEw9ij7Ndur7Wcrru_5eQNbSiNaiP4NQYWht5srEL";indexed="?0"

For the CESR encoded signature value I think there are two options:

1. Remove the CESR code prefix "0B", then encode the payload as base64 (with padding, not url safe)
2. Transform the CESR signature value into B-domain, then encode as base64 (not url safe). Introduce KERI CESR specific signature alg name for example "keri-ed25519" (or simply "keri-signature" as the CESR signature value already identifies the algorithm)

With option 1) and correct datatypes of Byte Sequence and Boolean the value looks like this:

Signature: signify=:hPSaI922OvLC0M8WMQoEDgt7xFoby6KX0JNW/8KMeaqpMoTu/0lrhKiZNbHwC0IdXk9ur3Ud2k6i/v5VOFIbBg==:;indexed=?0

I don't know if HTTP Message Signatures allows extending the Signature value with parameters. To avoid interop issues I'd suggest moving the "indexed" parameter to the Signature-Input header. This way the parameter is also included in the signed payload.

The Signature and Signature-Input headers then look like this:

Signature: signify=:hPSaI922OvLC0M8WMQoEDgt7xFoby6KX0JNW/8KMeaqpMoTu/0lrhKiZNbHwC0IdXk9ur3Ud2k6i/v5VOFIbBg==:
Signature-Input: signify=("@method" "@path" "content-length" "signify-resource" "signify-timestamp");created=1609459200;keyid="EICwDc-jYoUgNyMlAdg2iOFyeu56-RXvPRdFCG2luers";alg="ed25519";indexed=?0

The second option uses alg="keri-ed25519" and looks like this:

Signature: signify=:0BCE9Joj3bY68sLQzxYxCgQOC3vEWhvLopfQk1b/wox5qqkyhO7/SWuEqJk1sfALQh1eT26vdR3aTqL+/lU4UhsG:
Signature-Input: signify=("@method" "@path" "content-length" "signify-resource" "signify-timestamp");created=1609459200;keyid="EICwDc-jYoUgNyMlAdg2iOFyeu56-RXvPRdFCG2luers";alg="keri-ed25519";indexed=?0

References

• https://www.ietf.org/archive/id/draft-ietf-httpbis-message-signatures-17.html
• https://www.rfc-editor.org/rfc/rfc8941

[pfeairheller]

The concept of a "generic" client is nonsensical. There is a very specific sequence you must follow to boot strap an Agent in the KERIA service and very specific rules to follow regarding signing of requests, validating signatures of responses and passcode rotation. If you are doing that, you are a Signify client. You are overcomplicating things to say that there could be something more generic that being a Signify client.

[pfeairheller]

The signature on the header is a KERI signature and those are represented in CESR. Your library will need to generate CESR signatures, digests, prefixes etc etc to be a Signify client so there is no need to worry about interop with anyone that can't generate a CESR signature.