1# macaroon 2-- 3 import "gopkg.in/macaroon.v2" 4 5The macaroon package implements macaroons as described in the paper "Macaroons: 6Cookies with Contextual Caveats for Decentralized Authorization in the Cloud" 7(http://theory.stanford.edu/~ataly/Papers/macaroons.pdf) 8 9See the macaroon bakery packages at http://godoc.org/gopkg.in/macaroon-bakery.v2 10for higher level services and operations that use macaroons. 11 12## Usage 13 14```go 15const ( 16 TraceInvalid = TraceOpKind(iota) 17 18 // TraceMakeKey represents the operation of calculating a 19 // fixed length root key from the variable length input key. 20 TraceMakeKey 21 22 // TraceHash represents a keyed hash operation with one 23 // or two values. If there is only one value, it will be in Data1. 24 TraceHash 25 26 // TraceBind represents the operation of binding a discharge macaroon 27 // to its primary macaroon. Data1 holds the signature of the primary 28 // macaroon. 29 TraceBind 30 31 // TraceFail represents a verification failure. If present, this will always 32 // be the last operation in a trace. 33 TraceFail 34) 35``` 36 37#### func Base64Decode 38 39```go 40func Base64Decode(data []byte) ([]byte, error) 41``` 42Base64Decode base64-decodes the given data. It accepts both standard and URL 43encodings, both padded and unpadded. 44 45#### type Caveat 46 47```go 48type Caveat struct { 49 // Id holds the id of the caveat. For first 50 // party caveats this holds the condition; 51 // for third party caveats this holds the encrypted 52 // third party caveat. 53 Id []byte 54 55 // VerificationId holds the verification id. If this is 56 // non-empty, it's a third party caveat. 57 VerificationId []byte 58 59 // For third-party caveats, Location holds the 60 // ocation hint. Note that this is not signature checked 61 // as part of the caveat, so should only 62 // be used as a hint. 63 Location string 64} 65``` 66 67Caveat holds a first person or third party caveat. 68 69#### type Macaroon 70 71```go 72type Macaroon struct { 73} 74``` 75 76Macaroon holds a macaroon. See Fig. 7 of 77http://theory.stanford.edu/~ataly/Papers/macaroons.pdf for a description of the 78data contained within. Macaroons are mutable objects - use Clone as appropriate 79to avoid unwanted mutation. 80 81#### func New 82 83```go 84func New(rootKey, id []byte, loc string, version Version) (*Macaroon, error) 85``` 86New returns a new macaroon with the given root key, identifier, location and 87version. 88 89#### func (*Macaroon) AddFirstPartyCaveat 90 91```go 92func (m *Macaroon) AddFirstPartyCaveat(condition []byte) error 93``` 94AddFirstPartyCaveat adds a caveat that will be verified by the target service. 95 96#### func (*Macaroon) AddThirdPartyCaveat 97 98```go 99func (m *Macaroon) AddThirdPartyCaveat(rootKey, caveatId []byte, loc string) error 100``` 101AddThirdPartyCaveat adds a third-party caveat to the macaroon, using the given 102shared root key, caveat id and location hint. The caveat id should encode the 103root key in some way, either by encrypting it with a key known to the third 104party or by holding a reference to it stored in the third party's storage. 105 106#### func (*Macaroon) Bind 107 108```go 109func (m *Macaroon) Bind(sig []byte) 110``` 111Bind prepares the macaroon for being used to discharge the macaroon with the 112given signature sig. This must be used before it is used in the discharges 113argument to Verify. 114 115#### func (*Macaroon) Caveats 116 117```go 118func (m *Macaroon) Caveats() []Caveat 119``` 120Caveats returns the macaroon's caveats. This method will probably change, and 121it's important not to change the returned caveat. 122 123#### func (*Macaroon) Clone 124 125```go 126func (m *Macaroon) Clone() *Macaroon 127``` 128Clone returns a copy of the receiving macaroon. 129 130#### func (*Macaroon) Id 131 132```go 133func (m *Macaroon) Id() []byte 134``` 135Id returns the id of the macaroon. This can hold arbitrary information. 136 137#### func (*Macaroon) Location 138 139```go 140func (m *Macaroon) Location() string 141``` 142Location returns the macaroon's location hint. This is not verified as part of 143the macaroon. 144 145#### func (*Macaroon) MarshalBinary 146 147```go 148func (m *Macaroon) MarshalBinary() ([]byte, error) 149``` 150MarshalBinary implements encoding.BinaryMarshaler by formatting the macaroon 151according to the version specified by MarshalAs. 152 153#### func (*Macaroon) MarshalJSON 154 155```go 156func (m *Macaroon) MarshalJSON() ([]byte, error) 157``` 158MarshalJSON implements json.Marshaler by marshaling the macaroon in JSON format. 159The serialisation format is determined by the macaroon's version. 160 161#### func (*Macaroon) SetLocation 162 163```go 164func (m *Macaroon) SetLocation(loc string) 165``` 166SetLocation sets the location associated with the macaroon. Note that the 167location is not included in the macaroon's hash chain, so this does not change 168the signature. 169 170#### func (*Macaroon) Signature 171 172```go 173func (m *Macaroon) Signature() []byte 174``` 175Signature returns the macaroon's signature. 176 177#### func (*Macaroon) TraceVerify 178 179```go 180func (m *Macaroon) TraceVerify(rootKey []byte, discharges []*Macaroon) ([]Trace, error) 181``` 182TraceVerify verifies the signature of the macaroon without checking any of the 183first party caveats, and returns a slice of Traces holding the operations used 184when verifying the macaroons. 185 186Each element in the returned slice corresponds to the operation for one of the 187argument macaroons, with m at index 0, and discharges at 1 onwards. 188 189#### func (*Macaroon) UnmarshalBinary 190 191```go 192func (m *Macaroon) UnmarshalBinary(data []byte) error 193``` 194UnmarshalBinary implements encoding.BinaryUnmarshaler. It accepts both V1 and V2 195binary encodings. 196 197#### func (*Macaroon) UnmarshalJSON 198 199```go 200func (m *Macaroon) UnmarshalJSON(data []byte) error 201``` 202UnmarshalJSON implements json.Unmarshaller by unmarshaling the given macaroon in 203JSON format. It accepts both V1 and V2 forms encoded forms, and also a 204base64-encoded JSON string containing the binary-marshaled macaroon. 205 206After unmarshaling, the macaroon's version will reflect the version that it was 207unmarshaled as. 208 209#### func (*Macaroon) Verify 210 211```go 212func (m *Macaroon) Verify(rootKey []byte, check func(caveat string) error, discharges []*Macaroon) error 213``` 214Verify verifies that the receiving macaroon is valid. The root key must be the 215same that the macaroon was originally minted with. The check function is called 216to verify each first-party caveat - it should return an error if the condition 217is not met. 218 219The discharge macaroons should be provided in discharges. 220 221Verify returns nil if the verification succeeds. 222 223#### func (*Macaroon) VerifySignature 224 225```go 226func (m *Macaroon) VerifySignature(rootKey []byte, discharges []*Macaroon) ([]string, error) 227``` 228VerifySignature verifies the signature of the given macaroon with respect to the 229root key, but it does not validate any first-party caveats. Instead it returns 230all the applicable first party caveats on success. 231 232The caller is responsible for checking the returned first party caveat 233conditions. 234 235#### func (*Macaroon) Version 236 237```go 238func (m *Macaroon) Version() Version 239``` 240Version returns the version of the macaroon. 241 242#### type Slice 243 244```go 245type Slice []*Macaroon 246``` 247 248Slice defines a collection of macaroons. By convention, the first macaroon in 249the slice is a primary macaroon and the rest are discharges for its third party 250caveats. 251 252#### func (Slice) MarshalBinary 253 254```go 255func (s Slice) MarshalBinary() ([]byte, error) 256``` 257MarshalBinary implements encoding.BinaryMarshaler. 258 259#### func (*Slice) UnmarshalBinary 260 261```go 262func (s *Slice) UnmarshalBinary(data []byte) error 263``` 264UnmarshalBinary implements encoding.BinaryUnmarshaler. It accepts all known 265binary encodings for the data - all the embedded macaroons need not be encoded 266in the same format. 267 268#### type Trace 269 270```go 271type Trace struct { 272 RootKey []byte 273 Ops []TraceOp 274} 275``` 276 277Trace holds all toperations involved in verifying a macaroon, and the root key 278used as the initial verification key. This can be useful for debugging macaroon 279implementations. 280 281#### func (Trace) Results 282 283```go 284func (t Trace) Results() [][]byte 285``` 286Results returns the output from all operations in the Trace. The result from 287ts.Ops[i] will be in the i'th element of the returned slice. When a trace has 288resulted in a failure, the last element will be nil. 289 290#### type TraceOp 291 292```go 293type TraceOp struct { 294 Kind TraceOpKind `json:"kind"` 295 Data1 []byte `json:"data1,omitempty"` 296 Data2 []byte `json:"data2,omitempty"` 297} 298``` 299 300TraceOp holds one possible operation when verifying a macaroon. 301 302#### func (TraceOp) Result 303 304```go 305func (op TraceOp) Result(input []byte) []byte 306``` 307Result returns the result of computing the given operation with the given input 308data. If op is TraceFail, it returns nil. 309 310#### type TraceOpKind 311 312```go 313type TraceOpKind int 314``` 315 316TraceOpKind represents the kind of a macaroon verification operation. 317 318#### func (TraceOpKind) String 319 320```go 321func (k TraceOpKind) String() string 322``` 323String returns a string representation of the operation. 324 325#### type Version 326 327```go 328type Version uint16 329``` 330 331Version specifies the version of a macaroon. In version 1, the macaroon id and 332all caveats must be UTF-8-compatible strings, and the size of any part of the 333macaroon may not exceed approximately 64K. In version 2, all field may be 334arbitrary binary blobs. 335 336```go 337const ( 338 // V1 specifies version 1 macaroons. 339 V1 Version = 1 340 341 // V2 specifies version 2 macaroons. 342 V2 Version = 2 343 344 // LatestVersion holds the latest supported version. 345 LatestVersion = V2 346) 347``` 348 349#### func (Version) String 350 351```go 352func (v Version) String() string 353``` 354String returns a string representation of the version; for example V1 formats as 355"v1". 356