Note on JSON signing

We need to sign JSON objects in a few places in the ledger and connector
level APIs. After evaluating the options, we concluded:

Secure Messaging [1] depends on RDF Graph Normalization which is a fairly
complex process. We don't think it's a good idea to have a signature
standard have a complex dependency like that, despite the benefits. The
spec also isn't very widely used.

JSON Web Signatures (JWS) [2] normally contain the data they is signing. So
our objects would get bloated by a bunch of base64-encoded redundant JSON -
incredibly wasteful and ugly in our case. It was designed for signing
tokens, not objects in an API, so it really isn't meant for our use case.
Since transfers could get large with nesting, this is a dealbreaker.

We can deviate from standard JWS and just provide the signature by itself.
JWS library usually support this way of using it. So that's nice, but now
the standard doesn't specify how to canonicalize the JSON, what to call the
signature header field, what to call the signature field, where those
fields should be added in relation to the object being signed.

Fortunately, somebody else has already run into the exact same issue.

JCS [3] is designed for our use case exactly. It is building very closely
on JWS in the sense that it would be trivial to extend a JWS library with
JCS support. In most cases you'll even be able to use a JWS library to
verify and generate JCS signatures with minimal glue.

For these reasons, we plan to use JCS in the reference implementation for
now. Curious to hear everyone's input, the final decision on what the
long-term API will be is still open.

[1] https://web-payments.org/specs/source/secure-messaging/
[2] https://tools.ietf.org/html/rfc7515
[3] https://cyberphone.github.io/openkeystore/resources/docs/jcs.html