← Back to branch summary

~ubuntu-branches/ubuntu/vivid/juju-core/vivid-proposed

« back to all changes in this revision

Viewing changes to src/gopkg.in/macaroon.v1/README.md

  • Committer: Package Import Robot
  • Author(s): Curtis C. Hovey
  • Date: 2015-09-29 19:43:29 UTC
  • mfrom: (47.1.4 wily-proposed)
  • Revision ID: package-import@ubuntu.com-20150929194329-9y496tbic30hc7vp
Tags: 1.24.6-0ubuntu1~15.04.1
https://launchpad.net/bugs/1500916
https://launchpad.net/bugs/1497087
Backport of 1.24.6 from wily. (LP: #1500916, #1497087)

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/gopkg.in/macaroon.v1/README.md
 
1
# macaroon
 
2
--
 
3
    import "gopkg.in/macaroon.v1"
 
4
 
 
5
The macaroon package implements macaroons as described in the paper "Macaroons:
 
6
Cookies with Contextual Caveats for Decentralized Authorization in the Cloud"
 
7
(http://theory.stanford.edu/~ataly/Papers/macaroons.pdf)
 
8
 
 
9
See the macaroon bakery packages at http://godoc.org/gopkg.in/macaroon-bakery.v0
 
10
for higher level services and operations that use macaroons.
 
11
 
 
12
## Usage
 
13
 
 
14
#### type Caveat
 
15
 
 
16
```go
 
17
type Caveat struct {
 
18
        Id       string
 
19
        Location string
 
20
}
 
21
```
 
22
 
 
23
 
 
24
#### type Macaroon
 
25
 
 
26
```go
 
27
type Macaroon struct {
 
28
}
 
29
```
 
30
 
 
31
Macaroon holds a macaroon. See Fig. 7 of
 
32
http://theory.stanford.edu/~ataly/Papers/macaroons.pdf for a description of the
 
33
data contained within. Macaroons are mutable objects - use Clone as appropriate
 
34
to avoid unwanted mutation.
 
35
 
 
36
#### func  New
 
37
 
 
38
```go
 
39
func New(rootKey []byte, id, loc string) (*Macaroon, error)
 
40
```
 
41
New returns a new macaroon with the given root key, identifier and location.
 
42
 
 
43
#### func (*Macaroon) AddFirstPartyCaveat
 
44
 
 
45
```go
 
46
func (m *Macaroon) AddFirstPartyCaveat(caveatId string) error
 
47
```
 
48
AddFirstPartyCaveat adds a caveat that will be verified by the target service.
 
49
 
 
50
#### func (*Macaroon) AddThirdPartyCaveat
 
51
 
 
52
```go
 
53
func (m *Macaroon) AddThirdPartyCaveat(rootKey []byte, caveatId string, loc string) error
 
54
```
 
55
AddThirdPartyCaveat adds a third-party caveat to the macaroon, using the given
 
56
shared root key, caveat id and location hint. The caveat id should encode the
 
57
root key in some way, either by encrypting it with a key known to the third
 
58
party or by holding a reference to it stored in the third party's storage.
 
59
 
 
60
#### func (*Macaroon) Bind
 
61
 
 
62
```go
 
63
func (m *Macaroon) Bind(sig []byte)
 
64
```
 
65
Bind prepares the macaroon for being used to discharge the macaroon with the
 
66
given signature sig. This must be used before it is used in the discharges
 
67
argument to Verify.
 
68
 
 
69
#### func (*Macaroon) Caveats
 
70
 
 
71
```go
 
72
func (m *Macaroon) Caveats() []Caveat
 
73
```
 
74
Caveats returns the macaroon's caveats. This method will probably change, and
 
75
it's important not to change the returned caveat.
 
76
 
 
77
#### func (*Macaroon) Clone
 
78
 
 
79
```go
 
80
func (m *Macaroon) Clone() *Macaroon
 
81
```
 
82
Clone returns a copy of the receiving macaroon.
 
83
 
 
84
#### func (*Macaroon) Id
 
85
 
 
86
```go
 
87
func (m *Macaroon) Id() string
 
88
```
 
89
Id returns the id of the macaroon. This can hold arbitrary information.
 
90
 
 
91
#### func (*Macaroon) Location
 
92
 
 
93
```go
 
94
func (m *Macaroon) Location() string
 
95
```
 
96
Location returns the macaroon's location hint. This is not verified as part of
 
97
the macaroon.
 
98
 
 
99
#### func (*Macaroon) MarshalBinary
 
100
 
 
101
```go
 
102
func (m *Macaroon) MarshalBinary() ([]byte, error)
 
103
```
 
104
MarshalBinary implements encoding.BinaryMarshaler.
 
105
 
 
106
#### func (*Macaroon) MarshalJSON
 
107
 
 
108
```go
 
109
func (m *Macaroon) MarshalJSON() ([]byte, error)
 
110
```
 
111
MarshalJSON implements json.Marshaler.
 
112
 
 
113
#### func (*Macaroon) Signature
 
114
 
 
115
```go
 
116
func (m *Macaroon) Signature() []byte
 
117
```
 
118
Signature returns the macaroon's signature.
 
119
 
 
120
#### func (*Macaroon) UnmarshalBinary
 
121
 
 
122
```go
 
123
func (m *Macaroon) UnmarshalBinary(data []byte) error
 
124
```
 
125
UnmarshalBinary implements encoding.BinaryUnmarshaler.
 
126
 
 
127
#### func (*Macaroon) UnmarshalJSON
 
128
 
 
129
```go
 
130
func (m *Macaroon) UnmarshalJSON(jsonData []byte) error
 
131
```
 
132
UnmarshalJSON implements json.Unmarshaler.
 
133
 
 
134
#### func (*Macaroon) Verify
 
135
 
 
136
```go
 
137
func (m *Macaroon) Verify(rootKey []byte, check func(caveat string) error, discharges []*Macaroon) error
 
138
```
 
139
Verify verifies that the receiving macaroon is valid. The root key must be the
 
140
same that the macaroon was originally minted with. The check function is called
 
141
to verify each first-party caveat - it should return an error if the condition
 
142
is not met.
 
143
 
 
144
The discharge macaroons should be provided in discharges.
 
145
 
 
146
Verify returns true if the verification succeeds; if returns (false, nil) if the
 
147
verification fails, and (false, err) if the verification cannot be asserted (but
 
148
may not be false).
 
149
 
 
150
TODO(rog) is there a possible DOS attack that can cause this function to
 
151
infinitely recurse?
 
152
 
 
153
#### type Verifier
 
154
 
 
155
```go
 
156
type Verifier interface {
 
157
        Verify(m *Macaroon, rootKey []byte) (bool, error)
 
158
}
 
159
```