Skip to content

Commit 7c815d2

Browse files
joe-alewineJoe Alewine
joe-alewine
authored and
Joe Alewine
committed
[FAB-6546] Document ACL
Current implementation. Formatting. How to update. Change-Id: Ic5e14ea562c38144ac754f32f7cf02affe8d183a Signed-off-by: joe-alewine <Joe.Alewine@ibm.com>
1 parent 1a5fcca commit 7c815d2

File tree

2 files changed

+298
-0
lines changed

2 files changed

+298
-0
lines changed

‎docs/source/access_control.md

+297
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
# Access Control Lists (ACL)
2+
3+
## What is an Access Control List?
4+
5+
Fabric uses access control lists (ACLs) to manage access to resources by associating
6+
a **policy** --- which specifies a rule that evaluates to true or false, given a set
7+
of identities --- with the resource. Fabric contains a number of default ACLs. In this
8+
document, we'll talk about how they're formatted and how the defaults can be overridden.
9+
10+
But before we can do that, it's necessary to understand a little about resources
11+
and policies.
12+
13+
### Resources
14+
15+
Users interact with Fabric by targeting a [user chaincode](./chaincode4ade.html),
16+
[system chaincode](./chaincode4noah.html), or an [events stream source](./peer_event_services.html).
17+
As such, these endpoints are considered "resources" on which access control should be
18+
exercised.
19+
20+
Application developers need to be aware of these resources and the default
21+
policies associated with them. The complete list of these resources are found in
22+
`configtx.yaml`. You can look at a [sample `configtx.yaml` file here](http://github.com/hyperledger/fabric/blob/release-1.2/sampleconfig/configtx.yaml).
23+
24+
The resources named in `configtx.yaml` is an exhaustive list of all internal resources
25+
currently defined by Fabric. The loose convention adopted there is `<component>/<resource>`.
26+
So `cscc/GetConfigBlock` is the resource for the `GetConfigBlock` call in the `CSCC`
27+
component.
28+
29+
### Policies
30+
31+
Policies are fundamental to the way Fabric works because they allow the identity
32+
(or set of identities) associated with a request to be checked against the policy
33+
associated with the resource needed to fulfill the request. Endorsement policies
34+
are used to determine whether a transaction has been appropriately endorsed. The
35+
policies defined in the channel configuration are referenced as modification policies
36+
as well as for access control, and are defined in the channel configuration itself.
37+
38+
Policies can be structured in one of two ways: as `Signature` policies or as an
39+
`ImplicitMeta` policy.
40+
41+
#### `Signature` policies
42+
43+
These policies identify specific users who must sign in order for a policy
44+
to be satisfied. For example:
45+
46+
```
47+
Policies:
48+
MyPolicy:
49+
Type: Signature
50+
Rule: “Org1.Peer OR Org2.Peer”
51+
52+
```
53+
54+
This policy construct can be interpreted as: *the policy named `MyPolicy` can
55+
only be satisfied by the signature of of an identity with role of "a peer from
56+
Org1" or "a peer from Org2"*.
57+
58+
Signature policies support arbitrary combinations of `AND`, `OR`, and `NOutOf`,
59+
allowing the construction of extremely powerful rules like: "An admin of org A
60+
and two other admins, or 11 of 20 org admins".
61+
62+
#### `ImplicitMeta` policies
63+
64+
`ImplicitMeta` policies aggregate the result of policies deeper in the
65+
configuration hierarchy that are ultimately defined by `Signature` policies. They
66+
support default rules like "A majority of the organization admins". These policies
67+
use a different but still very simple syntax as compared to `Signature` policies:
68+
`<ALL|ANY|MAJORITY> <sub_policy>`.
69+
70+
For example: `ANY` `Readers` or `MAJORITY` `Admins`.
71+
72+
*Note that in the default policy configuration `Admins` have an operational role.
73+
Policies that specify that only Admins --- or some subset of Admins --- have access
74+
to a resource will tend to be for sensitive or operational aspects of the network
75+
(such as instantiating chaincode on a channel). `Writers` will tend to be able to
76+
propose ledger updates, such as a transaction, but will not typically have
77+
administrative permissions. `Readers` have a passive role. They can access
78+
information but do not have the permission to propose ledger updates nor do can
79+
they perform administrative tasks. These default policies can be added to,
80+
edited, or supplemented, for example by the new `peer` and `client` roles (if you
81+
have `NodeOU` support).*
82+
83+
Here's an example of an `ImplicitMeta` policy structure:
84+
85+
```
86+
Policies:
87+
AnotherPolicy:
88+
Type: ImplicitMeta
89+
Rule: "MAJORITY Admins"
90+
```
91+
92+
Here, the policy `AnotherPolicy` can be satisfied by the `MAJORITY` of `Admins`,
93+
where `Admins` is eventually being specified by lower level `Signature` policy.
94+
95+
### Where is access control specified?
96+
97+
Access control defaults exist inside `configtx.yaml`, the file that `configtxgen`
98+
uses to build channel configurations.
99+
100+
Access control can be updated one of two ways, either by editing `configtx.yaml`
101+
itself, which will propagate the ACL change to any new channels, or by updating
102+
access control in the channel configuration of a particular channel.
103+
104+
## How ACLs are formatted in `configtx.yaml`
105+
106+
ACLs are formatted as a key-value pair consisting of a resource function name
107+
followed by a string. To see what this looks like, reference this [sample configtx.yaml file](https://github.com/hyperledger/fabric/blob/release-1.2/sampleconfig/configtx.yaml).
108+
109+
Two excerpts from this sample:
110+
111+
```
112+
# ACL policy for invoking chaincodes on peer
113+
peer/Propose: /Channel/Application/Writers
114+
```
115+
116+
```
117+
# ACL policy for sending block events
118+
event/Block: /Channel/Application/Readers
119+
```
120+
121+
These ACLs define that access to `peer/Propose` and `event/Block` resources
122+
is restricted to identities satisfying the policy defined at the canonical path
123+
`/Channel/Application/Writers` and `/Channel/Application/Readers`, respectively.
124+
125+
### Updating ACL defaults in `configtx.yaml`
126+
127+
In cases where it will be necessary to override ACL defaults when bootstrapping
128+
a network, or to change the ACLs before a channel has been bootstrapped, the
129+
best practice will be to update `configtx.yaml`.
130+
131+
Let's say you want to modify the `peer/Propose` ACL default --- which specifies
132+
the policy for invoking chaincodes on a peer -- from `/Channel/Application/Writers`
133+
to a policy called `MyPolicy`.
134+
135+
This is done by adding a policy called `MyPolicy` (it could be called anything,
136+
but for this example we'll call it `MyPolicy`). The policy is defined in the
137+
`Application.Policies` section inside `configtx.yaml` and specifies a rule to be
138+
checked to grant or deny access to a user. For this example, we'll be creating a
139+
`Signature` policy identifying `SampleOrg.admin`.
140+
141+
```
142+
Policies: &ApplicationDefaultPolicies
143+
Readers:
144+
Type: ImplicitMeta
145+
Rule: "ANY Readers"
146+
Writers:
147+
Type: ImplicitMeta
148+
Rule: "ANY Writers"
149+
Admins:
150+
Type: ImplicitMeta
151+
Rule: "MAJORITY Admins"
152+
MyPolicy:
153+
Type: Signature
154+
Rule: "OR('SampleOrg.admin')"
155+
```
156+
157+
Then, edit the `Application: ACLs` section inside `configtx.yaml` to change
158+
`peer/Propose` from this:
159+
160+
`peer/Propose: /Channel/Application/Writers`
161+
162+
To this:
163+
164+
`peer/Propose: /Channel/Application/MyPolicy`
165+
166+
Once these fields have been changed in `configtx.yaml`, the `configtxgen` tool
167+
will use the policies and ACLs defined when creating a channel creation
168+
transaction. When appropriately signed and submitted by one of the admins of the
169+
consortium members, a new channel with the defined ACLs and policies is created.
170+
171+
Once `MyPolicy` has been bootstrapped into the channel configuration, it can also
172+
be referenced to override other ACL defaults. For example:
173+
174+
```
175+
SampleSingleMSPChannel:
176+
Consortium: SampleConsortium
177+
Application:
178+
<<: *ApplicationDefaults
179+
ACLs:
180+
<<: *ACLsDefault
181+
event/Block: /Channel/Application/MyPolicy
182+
```
183+
184+
This would restrict the ability to subscribe to block events to `SampleOrg.admin`.
185+
186+
If channels have already been created that want to use this ACL, they'll have
187+
to update their channel configurations one at a time using the following flow:
188+
189+
### Updating ACL defaults in the channel config
190+
191+
If channels have already been created that want to use `MyPolicy` to restrict
192+
access to `peer/Propose` --- or if they want to create ACLs they don't want
193+
other channels to know about --- they'll have to update their channel
194+
configurations one at a time through config update transactions.
195+
196+
*Note: Channel configuration transactions are an involved process we won't
197+
delve into here. If you want to read more about them check out our document on
198+
[channel configuration updates](./config_update.html) and our ["Adding an Org to a Channel" tutorial](./channel_update_tutorial.html).*
199+
200+
After pulling, translating, and stripping the configuration block of its metadata,
201+
you would edit the configuration by adding `MyPolicy` under `Application: policies`,
202+
where the `Admins`, `Writers`, and `Readers` policies already live.
203+
204+
```
205+
"MyPolicy": {
206+
"mod_policy": "Admins",
207+
"policy": {
208+
"type": 1,
209+
"value": {
210+
"identities": [
211+
{
212+
"principal": {
213+
"msp_identifier": "SampleOrg",
214+
"role": "ADMIN"
215+
},
216+
"principal_classification": "ROLE"
217+
}
218+
],
219+
"rule": {
220+
"n_out_of": {
221+
"n": 1,
222+
"rules": [
223+
{
224+
"signed_by": 0
225+
}
226+
]
227+
}
228+
},
229+
"version": 0
230+
}
231+
},
232+
"version": "0"
233+
},
234+
```
235+
236+
Note in particular the `msp_identifer` and `role` here.
237+
238+
Then, in the ACLs section of the config, change the `peer/Propose` ACL from
239+
this:
240+
241+
```
242+
"peer/Propose": {
243+
"policy_ref": "/Channel/Application/Writers"
244+
```
245+
246+
To this:
247+
248+
```
249+
"peer/Propose": {
250+
"policy_ref": "/Channel/Application/MyPolicy"
251+
```
252+
253+
Note: If you do not have ACLs defined in your channel configuration, you will
254+
have to add the entire ACL structure.
255+
256+
Once the configuration has been updated, it will need to be submitted by the
257+
usual channel update process.
258+
259+
### Satisfying an ACL that requires access to multiple resources
260+
261+
If a member makes a request that calls multiple system chaincodes, all of the ACLs
262+
for those system chaincodes must be satisfied.
263+
264+
For example, `peer/Propose` refers to any proposal request on a channel. If the
265+
particular proposal requires access to two system chaincodes that requires an
266+
identity satisfying `Writers` and one system chaincode that requires an identity
267+
satisfying `MyPolicy`, then the member submitting the proposal must have an identity
268+
that evaluates to "true" for both `Writers` and `MyPolicy`.
269+
270+
In the default configuration, `Writers` is a signature policy whose `rule` is
271+
`SampleOrg.member`. In other words, "any member of my organization". `MyPolicy`,
272+
listed above, has a rule of `SampleOrg.admin`, or "any admin of my organization".
273+
To satisfy these ACLs, the member would have to be both an administrator and a
274+
member of `SampleOrg`. By default, all administrators are members (though not all
275+
administrators are members), but it is possible to overwrite these policies to
276+
whatever you want them to be. As a result, it's important to keep track of these
277+
policies to ensure that the ACLs for peer proposals are not impossible to satisfy
278+
(unless that is the intention).
279+
280+
#### Migration considerations for customers using the experimental ACL feature
281+
282+
Previously, the management of access control lists was done in an `isolated_data`
283+
section of the channel creation transaction and updated via `PEER_RESOURCE_UPDATE`
284+
transactions. Originally, it was thought that the `resources` tree would handle the
285+
update of several functions that, ultimately, were handled in other ways, so
286+
maintaining a separate parallel peer configuration tree was judged to be unnecessary.
287+
288+
Migration for customers using the experimental resources tree in v1.1 is possible.
289+
Because the official v1.2 release does not support the old ACL methods, the network
290+
operators should shut down all their peers. Then, they should upgrade them to v1.2,
291+
submit a channel reconfiguration transaction which enables the v1.2 capability and
292+
sets the desired ACLs, and then finally restart the upgraded peers. The restarted
293+
peers will immediately consume the new channel configuration and enforce the ACLs as
294+
desired.
295+
296+
<!--- Licensed under Creative Commons Attribution 4.0 International License
297+
https://creativecommons.org/licenses/by/4.0/ -->

‎docs/source/ops_guide.rst

+1
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Operations Guides
1010
configtx
1111
endorsement-policies
1212
pluggable_endorsement_and_validation
13+
access_control.md
1314
error-handling
1415
logging-control
1516
enable_tls

0 commit comments

Comments
 (0)