macaroon
--
import "gopkg.in/macaroon.v2"
The macaroon package implements macaroons as described in the paper "Macaroons:
Cookies with Contextual Caveats for Decentralized Authorization in the Cloud"
(http://theory.stanford.edu/~ataly/Papers/macaroons.pdf)
See the macaroon bakery packages at http://godoc.org/gopkg.in/macaroon-bakery.v2
for higher level services and operations that use macaroons.
Usage
const (
TraceInvalid = TraceOpKind(iota)
TraceMakeKey
TraceHash
TraceBind
TraceFail
)
func Base64Decode
func Base64Decode(data []byte) ([]byte, error)
Base64Decode base64-decodes the given data. It accepts both standard and URL
encodings, both padded and unpadded.
type Caveat
type Caveat struct {
Id []byte
VerificationId []byte
Location string
}
Caveat holds a first person or third party caveat.
type Macaroon
type Macaroon struct {
}
Macaroon holds a macaroon. See Fig. 7 of
http://theory.stanford.edu/~ataly/Papers/macaroons.pdf for a description of the
data contained within. Macaroons are mutable objects - use Clone as appropriate
to avoid unwanted mutation.
func New
func New(rootKey, id []byte, loc string, version Version) (*Macaroon, error)
New returns a new macaroon with the given root key, identifier, location and
version.
func (*Macaroon) AddFirstPartyCaveat
func (m *Macaroon) AddFirstPartyCaveat(condition []byte) error
AddFirstPartyCaveat adds a caveat that will be verified by the target service.
func (*Macaroon) AddThirdPartyCaveat
func (m *Macaroon) AddThirdPartyCaveat(rootKey, caveatId []byte, loc string) error
AddThirdPartyCaveat adds a third-party caveat to the macaroon, using the given
shared root key, caveat id and location hint. The caveat id should encode the
root key in some way, either by encrypting it with a key known to the third
party or by holding a reference to it stored in the third party's storage.
func (*Macaroon) Bind
func (m *Macaroon) Bind(sig []byte)
Bind prepares the macaroon for being used to discharge the macaroon with the
given signature sig. This must be used before it is used in the discharges
argument to Verify.
func (*Macaroon) Caveats
func (m *Macaroon) Caveats() []Caveat
Caveats returns the macaroon's caveats. This method will probably change, and
it's important not to change the returned caveat.
func (*Macaroon) Clone
func (m *Macaroon) Clone() *Macaroon
Clone returns a copy of the receiving macaroon.
func (*Macaroon) Id
func (m *Macaroon) Id() []byte
Id returns the id of the macaroon. This can hold arbitrary information.
func (*Macaroon) Location
func (m *Macaroon) Location() string
Location returns the macaroon's location hint. This is not verified as part of
the macaroon.
func (*Macaroon) MarshalBinary
func (m *Macaroon) MarshalBinary() ([]byte, error)
MarshalBinary implements encoding.BinaryMarshaler by formatting the macaroon
according to the version specified by MarshalAs.
func (*Macaroon) MarshalJSON
func (m *Macaroon) MarshalJSON() ([]byte, error)
MarshalJSON implements json.Marshaler by marshaling the macaroon in JSON format.
The serialisation format is determined by the macaroon's version.
func (*Macaroon) SetLocation
func (m *Macaroon) SetLocation(loc string)
SetLocation sets the location associated with the macaroon. Note that the
location is not included in the macaroon's hash chain, so this does not change
the signature.
func (*Macaroon) Signature
func (m *Macaroon) Signature() []byte
Signature returns the macaroon's signature.
func (*Macaroon) TraceVerify
func (m *Macaroon) TraceVerify(rootKey []byte, discharges []*Macaroon) ([]Trace, error)
TraceVerify verifies the signature of the macaroon without checking any of the
first party caveats, and returns a slice of Traces holding the operations used
when verifying the macaroons.
Each element in the returned slice corresponds to the operation for one of the
argument macaroons, with m at index 0, and discharges at 1 onwards.
func (*Macaroon) UnmarshalBinary
func (m *Macaroon) UnmarshalBinary(data []byte) error
UnmarshalBinary implements encoding.BinaryUnmarshaler. It accepts both V1 and V2
binary encodings.
func (*Macaroon) UnmarshalJSON
func (m *Macaroon) UnmarshalJSON(data []byte) error
UnmarshalJSON implements json.Unmarshaller by unmarshaling the given macaroon in
JSON format. It accepts both V1 and V2 forms encoded forms, and also a
base64-encoded JSON string containing the binary-marshaled macaroon.
After unmarshaling, the macaroon's version will reflect the version that it was
unmarshaled as.
func (*Macaroon) Verify
func (m *Macaroon) Verify(rootKey []byte, check func(caveat string) error, discharges []*Macaroon) error
Verify verifies that the receiving macaroon is valid. The root key must be the
same that the macaroon was originally minted with. The check function is called
to verify each first-party caveat - it should return an error if the condition
is not met.
The discharge macaroons should be provided in discharges.
Verify returns nil if the verification succeeds.
func (*Macaroon) VerifySignature
func (m *Macaroon) VerifySignature(rootKey []byte, discharges []*Macaroon) ([]string, error)
VerifySignature verifies the signature of the given macaroon with respect to the
root key, but it does not validate any first-party caveats. Instead it returns
all the applicable first party caveats on success.
The caller is responsible for checking the returned first party caveat
conditions.
func (*Macaroon) Version
func (m *Macaroon) Version() Version
Version returns the version of the macaroon.
type Slice
type Slice []*Macaroon
Slice defines a collection of macaroons. By convention, the first macaroon in
the slice is a primary macaroon and the rest are discharges for its third party
caveats.
func (Slice) MarshalBinary
func (s Slice) MarshalBinary() ([]byte, error)
MarshalBinary implements encoding.BinaryMarshaler.
func (*Slice) UnmarshalBinary
func (s *Slice) UnmarshalBinary(data []byte) error
UnmarshalBinary implements encoding.BinaryUnmarshaler. It accepts all known
binary encodings for the data - all the embedded macaroons need not be encoded
in the same format.
type Trace
type Trace struct {
RootKey []byte
Ops []TraceOp
}
Trace holds all toperations involved in verifying a macaroon, and the root key
used as the initial verification key. This can be useful for debugging macaroon
implementations.
func (Trace) Results
func (t Trace) Results() [][]byte
Results returns the output from all operations in the Trace. The result from
ts.Ops[i] will be in the i'th element of the returned slice. When a trace has
resulted in a failure, the last element will be nil.
type TraceOp
type TraceOp struct {
Kind TraceOpKind `json:"kind"`
Data1 []byte `json:"data1,omitempty"`
Data2 []byte `json:"data2,omitempty"`
}
TraceOp holds one possible operation when verifying a macaroon.
func (TraceOp) Result
func (op TraceOp) Result(input []byte) []byte
Result returns the result of computing the given operation with the given input
data. If op is TraceFail, it returns nil.
type TraceOpKind
type TraceOpKind int
TraceOpKind represents the kind of a macaroon verification operation.
func (TraceOpKind) String
func (k TraceOpKind) String() string
String returns a string representation of the operation.
type Version
type Version uint16
Version specifies the version of a macaroon. In version 1, the macaroon id and
all caveats must be UTF-8-compatible strings, and the size of any part of the
macaroon may not exceed approximately 64K. In version 2, all field may be
arbitrary binary blobs.
const (
V1 Version = 1
V2 Version = 2
LatestVersion = V2
)
func (Version) String
func (v Version) String() string
String returns a string representation of the version; for example V1 formats as
"v1".