-
Notifications
You must be signed in to change notification settings - Fork 48
/
format.txt
119 lines (79 loc) · 3.76 KB
/
format.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
Current Format
--------------
Left empty so the proposed schemes can be discussed. Shortcomings discussed
here: https://docs.google.com/document/d/1On_ILeQFVFXaN8ZSitZ9UarZCB-t_cRInSmJ-HVofCU/edit
Binary Format
-------------
Terminal tokens are in all-capitals, and all except for EOS and VERSION are
byte sequences in the following format:
<field type: varuint64> <field length: varuint64=N> <field content: N bytes>
where varuint64 describes an unsigned integer in variable length
encoding, as described here.
https://developers.google.com/protocol-buffers/docs/encoding#varints
To paraphrase that description, a varuint64 number consists of a sequence of bytes:
x1, x2, ..., xn
where x1... x(n-1) are in the range 0x80 to 0xff and xn is in the range
0x0..0x7f. That is, all but the last byte has its most significant bit set.
The encoded number is (x1 & 0x7f) | (x2 & 0x7f) << 7 | ... xn << (n * 7).
That is, each byte encodes 7 bits of the resulting number,
least-significant bits first.
Field type values for the terminal tokens are as follows:
LOCATION=1
IDENTIFIER=2
VID=4
SIGNATURE=6
EOS is the single byte zero.
VERSION is a single byte with the value 2.
The grammar is as follows, in YACC-like syntax:
macaroon: VERSION opt_location IDENTIFIER EOS caveats EOS SIGNATURE
caveats: caveat caveats
|
caveat: opt_location IDENTIFIER opt_vid EOS
opt_vid:
| VID
opt_location:
| LOCATION
JSON Format
-----------
The JSON format should be a mechanical translation of the above format with
the following specification.
All fields other than the version and location fields may contain arbitrary
binary data, though per-service conventions are free to impose stricter
requirements - these are outside the scope of this document.
Locations and the version should contain Unicode strings, although as these
are unverified data, implementations do not need to be strict about rejecting
non-UTF-8 byte sequences when converting from the binary format - for example
an implementation may choose to map unknown characters to 0xfffd values.
The version field should contain a string holding a numeric version number.
The initial version specified in this document is "2", indicating the major
version.
To handle binary data, other fields may be encoded as hexadecimal, base64 or
UTF-8. If a field is named *x* below, it may be specified in base64 with the
name *x*64. The hex format should allow both upper and lower case digits; the
base64 format should allow both URL-safe and standard base64 encodings with
optional "=" pad characters. The UTF-8 format can be used when the field
contains a valid sequence of UTF-8 bytes that can be encoded without loss as a
JSON string. In this case the JSON string should be interpreted as a sequence
of UTF-8 bytes after decoding for the purposes of signature calculation.
Implementations should reject JSON objects containing more than one
representation of the same field.
For example, all the following objects encode a caveat with the same id:
{"i": "Ou?T"}
{"i64": "T3U/VA=="}
{"i64": "T3U_VA=="}
{"i64": "T3U/VA"}
{"i64": "T3U_VA"}
The following object is an invalid caveat:
{"i": "foo", "i64": "Zm9v"}
The JSON object fields as are follows.
`v` (string): The version of the macaroon encoding used. Currently
this should be the string "2".
`i` (data): The macaroon identifier
`l` (optional string): The location of the macaroon.
`c` (array): A JSON array an object for each caveat.
`s` (data): The signature (must decode to exactly 32 bytes)
Each caveat is an object holding the following fields:
`i` (data): The caveat identifier.
`l` (optional string): The location of a third party caveat.
This must not be present if the VID (`v` field) is present.
`v` (data): The verification id (VID).