160 lines
4 KiB
Markdown
160 lines
4 KiB
Markdown
|
# macaroon
|
||
|
|
--
|
||
|
|
import "gopkg.in/macaroon.v1"
|
||
|
|
|
||
|
|
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.v0
|
||
|
|
for higher level services and operations that use macaroons.
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
#### type Caveat
|
||
|
|
|
||
|
|
```go
|
||
|
|
type Caveat struct {
|
||
|
|
Id string
|
||
|
|
Location string
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
|
||
|
|
#### type Macaroon
|
||
|
|
|
||
|
|
```go
|
||
|
|
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
|
||
|
|
|
||
|
|
```go
|
||
|
|
func New(rootKey []byte, id, loc string) (*Macaroon, error)
|
||
|
|
```
|
||
|
|
New returns a new macaroon with the given root key, identifier and location.
|
||
|
|
|
||
|
|
#### func (*Macaroon) AddFirstPartyCaveat
|
||
|
|
|
||
|
|
```go
|
||
|
|
func (m *Macaroon) AddFirstPartyCaveat(caveatId string) error
|
||
|
|
```
|
||
|
|
AddFirstPartyCaveat adds a caveat that will be verified by the target service.
|
||
|
|
|
||
|
|
#### func (*Macaroon) AddThirdPartyCaveat
|
||
|
|
|
||
|
|
```go
|
||
|
|
func (m *Macaroon) AddThirdPartyCaveat(rootKey []byte, caveatId string, 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
|
||
|
|
|
||
|
|
```go
|
||
|
|
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
|
||
|
|
|
||
|
|
```go
|
||
|
|
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
|
||
|
|
|
||
|
|
```go
|
||
|
|
func (m *Macaroon) Clone() *Macaroon
|
||
|
|
```
|
||
|
|
Clone returns a copy of the receiving macaroon.
|
||
|
|
|
||
|
|
#### func (*Macaroon) Id
|
||
|
|
|
||
|
|
```go
|
||
|
|
func (m *Macaroon) Id() string
|
||
|
|
```
|
||
|
|
Id returns the id of the macaroon. This can hold arbitrary information.
|
||
|
|
|
||
|
|
#### func (*Macaroon) Location
|
||
|
|
|
||
|
|
```go
|
||
|
|
func (m *Macaroon) Location() string
|
||
|
|
```
|
||
|
|
Location returns the macaroon's location hint. This is not verified as part of
|
||
|
|
the macaroon.
|
||
|
|
|
||
|
|
#### func (*Macaroon) MarshalBinary
|
||
|
|
|
||
|
|
```go
|
||
|
|
func (m *Macaroon) MarshalBinary() ([]byte, error)
|
||
|
|
```
|
||
|
|
MarshalBinary implements encoding.BinaryMarshaler.
|
||
|
|
|
||
|
|
#### func (*Macaroon) MarshalJSON
|
||
|
|
|
||
|
|
```go
|
||
|
|
func (m *Macaroon) MarshalJSON() ([]byte, error)
|
||
|
|
```
|
||
|
|
MarshalJSON implements json.Marshaler.
|
||
|
|
|
||
|
|
#### func (*Macaroon) Signature
|
||
|
|
|
||
|
|
```go
|
||
|
|
func (m *Macaroon) Signature() []byte
|
||
|
|
```
|
||
|
|
Signature returns the macaroon's signature.
|
||
|
|
|
||
|
|
#### func (*Macaroon) UnmarshalBinary
|
||
|
|
|
||
|
|
```go
|
||
|
|
func (m *Macaroon) UnmarshalBinary(data []byte) error
|
||
|
|
```
|
||
|
|
UnmarshalBinary implements encoding.BinaryUnmarshaler.
|
||
|
|
|
||
|
|
#### func (*Macaroon) UnmarshalJSON
|
||
|
|
|
||
|
|
```go
|
||
|
|
func (m *Macaroon) UnmarshalJSON(jsonData []byte) error
|
||
|
|
```
|
||
|
|
UnmarshalJSON implements json.Unmarshaler.
|
||
|
|
|
||
|
|
#### func (*Macaroon) Verify
|
||
|
|
|
||
|
|
```go
|
||
|
|
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 true if the verification succeeds; if returns (false, nil) if the
|
||
|
|
verification fails, and (false, err) if the verification cannot be asserted (but
|
||
|
|
may not be false).
|
||
|
|
|
||
|
|
TODO(rog) is there a possible DOS attack that can cause this function to
|
||
|
|
infinitely recurse?
|
||
|
|
|
||
|
|
#### type Verifier
|
||
|
|
|
||
|
|
```go
|
||
|
|
type Verifier interface {
|
||
|
|
Verify(m *Macaroon, rootKey []byte) (bool, error)
|
||
|
|
}
|
||
|
|
```
|