Update readme with warnings on serialization

[yousefamar]

Macaroons are serialized, using Base64 URL safe encoding RFC 4648. This way you can very easily append it to query string within URIs.

As far as I can tell, they're not. You seem to have some extra line prefixes in addition (packet headers for annotation). This resulted in hours of debugging for us because we assumed we could use the serialized data across lanugages/libaries by URL and Base64 decoding macaroons.

It would be useful to future devs if there was some sort of warning in the readme.

[yousefamar]

On further investigation, it seems that most libraries (de)serialize in a similar manner to this one, as a sort of standard set by libmacaroons, and that the libraries that don't (e.g. ocaml-macaroons) are the ones that are "incompatible" because their (de)serialization is "broken". Might be useful to have as a warning anyway.

[nitram509]

Thanks for your feedback.
Indeed, Bas64 URL safe variant is kind of tricky, because it is NOT compatible with regular Base64.
It uses different symbols, which cause regular parser to fail.

I'll add short notice in the README, to make this pitfall more explicit.

[yousefamar]

Thanks, but to clarify, I meant specifically that the data itself is modified in addition to encoding. To use your example MDAyNGxvY2F0aW9uIGh0dHA6Ly93d3cuZXhhbXBsZS5vcmcKMDAyNmlkZW50aWZpZXIgd2UgdXNlZCBvdXIgc2VjcmV0IGtleQowMDJmc2lnbmF0dXJlIOPZ4CkIUmxMADmuFRFBFdl_3Wi_K6N5s0Kq8PYX0FUvCg, is deserialized as:

location http://www.example.org
identifier we used our secret key
signature e3d9e02908526c4c0039ae15114115d97fdd68bf2ba379b342aaf0f617d0552f

Note the hex signature, and the lack of hex packet prefixes denoting the packet size. Meanwhile, a URL-safe Base64 decode looks like this:

0024location http://www.example.org
0026identifier we used our secret key
002fsignature ãÙà).RlL.9®..A.Ù.Ýh¿+£y³Bªðö.ÐU/

Is this a different variant that is spec'd somewhere, or just to match what libmacaroons decided to do for serialization?