GEMINI: 112812 unis_aa_usage.txt

File 112812 unis_aa_usage.txt, 14.6 KB (added by hmussman@bbn.com, 7 years ago)
Line 
1Interacting with the UNIS Security Model for GEMINI
2
3==== Overview =====
4
5Testing instance: https://monitor.incntre.iu.edu:9000
6
7The UNIS service with AA enabled expects SSL connections and client/user certificates.  The testing instance is configured to accept certificates signed by a trusted CA.  Any GENI certificate signed by a CA in genica.bundle will work.  It would be very easy to add additonal trusted CAs for testing purposes if necessary.  The ability to verify the client/user certificates is what I will call "authenticated" (AuthN) use of the UNIS service.  Without SSL, UNIS reverts back to the open model that we currently have running for GEMINI at http://unis.incntre.iu.edu:8888
8
9The current model for "authorized" (AuthZ) use is handled by ABAC within UNIS.  The AuthZ component is modular and can easily be disabled with UNIS settings.  New AuthZ mechanisms with different policies could also be written and enabled.  With all AuthZ modules disabled, any "authenticated" users have full read/write access to UNIS over SSL.
10
11The GEMINI-AuthZ module restricts user access to UNIS resources based on slice UUIDs.  To associate a slice with a user, GEMINI-AuthZ adds a /register_slice endpoint to UNIS.  This endpoint accepts a GENI slice credential, and after validating the credential against the user certificate, creates the default slice_admin ABAC roles, and stores the user and attribute certifacates.  GEMINI-AuthZ then restricts read/write access to resources based on if the user has slice_admin attributes.  Network resources added to UNIS are required to have a valid slice_uuid property.
12
13GEMINI-AuthZ also adds the /add_credential endpoint to UNIS allowing for new attribute certificates to be added to the ABAC store.  Example usage is shown below.  The current implementation accepts DER-encoded credentials created with creddy, but the interface could be extended to accept the XML-based delegated user credentials used in GENI (similar to how /register_slice accepts a GENI slice credential).
14
15Beyond the two endpoints introduced by GEMINI-AuthZ, the UNIS API remains unchanged.
16
17===== Client Programs =====
18
19A python UNIS client is available here:
20https://github.com/downloads/GENI-GEMINI/GEMINI/unis_client.py
21
22A browser can also be used to query UNIS as long as you import your user certificate.
23
24To convert GENI manifests into UNIS format, use unisencoder available here:
25https://github.com/downloads/GENI-GEMINI/GEMINI/unisencoder.tar.gz
26
27$ tar -zxf unisencoder.tar.gz
28$ cd unisencoder
29$ sudo python setup.py install
30
31creddy is available from http://abac.deterlab.net/
32
33===== Example Usage =====
34
35The following output shows how one can use UNIS with existing GENI tools.  Substitute your own credentials to test on your own.  Note that GENI users would not typically interact with UNIS directly, but running GEMINI services and the GEMINI instrumentation process will.
36
37
38::Create GENI slice::
39
40$ omni.py -f pg createslice ezraslice
41$ omni.py -f pg renewslice ezraslice 20121207T00:00:00Z
42$ omni.py -f pg -a pg-utah createsliver ezraslice 2node.rspec
43
44Get the manifest:
45
46$ omni.py -f pg -a pg-utah listresources ezraslice -o
47INFO:omni:Writing to 'ezraslice-manifest-rspec-www-emulab-net-protogeniv2.xml'
48
49Get the slice credential:
50
51$ omni.py -f pg -a pg-utah getslicecred ezraslice -o
52INFO:omni:Retrieved slice cred for slice urn:publicid:IDN+emulab.net+slice+ezraslice
53INFO:omni:Wrote slice ezraslice credential to file 'ezraslice-cred.xml'
54
55Convert the manifest to UNIS:
56
57$ export PYTHONPATH=/opt/gcf/src
58$ unisencoder -t rspec3 --slice_cred ezraslice-cred.xml --out ezraslice.unis ezraslice-manifest-rspec-www-emulab-net-protogeniv2.xml
59
60Now the user "experiment" is created, we have the manifest in the correct format, and we're ready to interact with UNIS.
61
62::Query UNIS without registered slice::
63
64Using the same GENI user keypair as the omni commands above.
65
66$ ./unis_client.py https://monitor.incntre.iu.edu:9000/topologies GET ssl/kissel.pem ssl/kissel.key
67
68Enter PEM pass phrase:
69
70Server Response: 403 Forbidden
71Response data (55 bytes):
72================================================================================
73{"message": "'GEMINI: no registered slices for user'"}
74
75================================================================================
76
77Current policy prohibits interacting with UNIS unless the user has registered a slice.  This also includes POSTing resources to UNIS.
78
79
80::Register slice::
81
82We can let UNIS know about a GENI slice given a slice credential.
83
84$ ./unis_client.py https://monitor.incntre.iu.edu:9000/register_slice POST ssl/kissel.pem ssl/kissel.key ~/geni/ezraslice-cred.xml
85
86Enter PEM pass phrase:
87
88Server Response: 200 OK
89Response data (0 bytes):
90================================================================================
91
92================================================================================
93
94A "200 OK" response indicates that the slice credential is now registered in UNIS and associated with the user identity (kissel).
95
96If you try to register a slice credential that doesn't belong to you:
97
98$ ./unis_client.py https://monitor.incntre.iu.edu:9000/register_slice POST ssl/encrypted_gpo.pem ssl/unencrypted_gpo.key ~/geni/ezraslice-cred.xml
99
100
101Server Response: 400 Bad Request
102Response data (62 bytes):
103================================================================================
104{"message": "'Client cert does not match credential owner!'"}
105
106================================================================================
107
108The request above tried to unsuccessfully register the slice credential using a different user certificate than the slice owner.  This prevents another user from hijacking someone else's credential file and treating it as their own.  You also can't register an expired slice credential, etc.
109
110
111::Query with registered slice::
112
113Let's try to look for available topologies:
114
115$ ./unis_client.py https://monitor.incntre.iu.edu:9000/topologies GET ssl/kissel.pem ssl/kissel.key
116
117Enter PEM pass phrase:
118
119Server Response: 200 OK
120Response data (2 bytes):
121================================================================================
122[]
123================================================================================
124
125The query to UNIS will complete now that the user has a registered slice, but the response is empty because UNIS does not contain any resources for that slice.
126
127
128::Push slice resources to UNIS::
129
130Let's push the manifest (in UNIS format) to UNIS.
131
132$ ./unis_client.py https://monitor.incntre.iu.edu:9000/topologies POST ssl/kissel.pem ssl/kissel.key ~/geni/ezraslice.unis
133
134Enter PEM pass phrase:
135
136Server Response: 201 Created
137Response data (1322 bytes):
138================================================================================
139{
140  "selfRef": "https://monitor.incntre.iu.edu:9000/topologies/emulab.net_slice_ezraslice",
141  "links": [
142    {
143      "href": "https://monitor.incntre.iu.edu:9000/links/emulab.net_slice_ezraslice_link_lan0",
144      "rel": "full"
145    }
146  ],
147  "urn": "urn:publicid:IDN+emulab.net+slice+ezraslice",
148  "ts": 1354113680393753,
149  "id": "emulab.net_slice_ezraslice",
150  "nodes": [
151    {
152      "href": "https://monitor.incntre.iu.edu:9000/nodes/VM.ezraslice.emulab-net.emulab.net",
153      "rel": "full"
154    },
155    {
156      "href": "https://monitor.incntre.iu.edu:9000/nodes/VM-0.ezraslice.emulab-net.emulab.net",
157      "rel": "full"
158    }
159  ],
160  "properties": {
161    "geni": {
162      "generated": "2012-11-26T19:46:11Z",
163      "slice_urn": "urn:publicid:IDN+emulab.net+slice+ezraslice",
164      "expires": "2012-12-03T14:15:44Z",
165      "type": "manifest",
166      "generated_by": "Flack",
167      "slice_uuid": "e6037ca6-3965-11e2-9f72-001143e453fe"
168    }
169  },
170  "$schema": "http://unis.incntre.iu.edu/schema/20120709/domain#",
171  "ports": [
172    {
173      "href": "https://monitor.incntre.iu.edu:9000/ports/emulab.net_slice_ezraslice_interface_VM%3Aif0",
174      "rel": "full"
175    },
176    {
177      "href": "https://monitor.incntre.iu.edu:9000/ports/emulab.net_slice_ezraslice_interface_VM-0%3Aif0",
178      "rel": "full"
179    }
180  ]
181}
182================================================================================
183
184The slice topology is now in UNIS and you can query the resources as usual.  For example, if you want the node object named "VM":
185
186$ ./unis_client.py https://monitor.incntre.iu.edu:9000/nodes?name=VM GET ssl/kissel.pem ssl/kissel.key ~/geni/ezraslice.unis
187name=VM
188Enter PEM pass phrase:
189
190Server Response: 200 OK
191Response data (1299 bytes):
192================================================================================
193[
194  {
195    "$schema": "http://unis.incntre.iu.edu/schema/20120709/node#",
196    "name": "VM",
197    "selfRef": "https://monitor.incntre.iu.edu:9000/nodes/VM.ezraslice.emulab-net.emulab.net",
198    "urn": "urn:publicid:IDN+emulab.net+slice+ezraslice+node+VM",
199    "ts": 1354113680391641,
200    "relations": {
201      "over": [
202        {
203          "href": "urn:publicid:IDN+emulab.net+node+pc509",
204          "rel": "full"
205        }
206      ]
207    },
208    "id": "VM.ezraslice.emulab-net.emulab.net",
209    "properties": {
210      "geni": {
211        "exclusive": false,
212        "component_id": "urn:publicid:IDN+emulab.net+node+pc509",
213        "slice_urn": "urn:publicid:IDN+emulab.net+slice+ezraslice",
214        "slice_uuid": "e6037ca6-3965-11e2-9f72-001143e453fe",
215        "sliver_id": "urn:publicid:IDN+emulab.net+sliver+101759",
216        "hosts": [
217          {
218            "hostname": "VM.ezraslice.emulab-net.emulab.net"
219          }
220        ],
221        "client_id": "VM",
222        "sliver_type": {
223          "name": "emulab-openvz"
224        },
225        "component_manager_id": "urn:publicid:IDN+emulab.net+authority+cm"
226      }
227    },
228    "ports": [
229      {
230        "href": "https://monitor.incntre.iu.edu:9000/ports/emulab.net_slice_ezraslice_interface_VM%3Aif0",
231        "rel": "full"
232      }
233    ]
234  }
235]
236================================================================================
237
238::Other users::
239
240Another user (my GPO certificate) registers and pushes a slice (exact same 2 node topology as before):
241
242$ ./unis_client.py https://monitor.incntre.iu.edu:9000/register_slice POST ssl/encrypted_gpo.pem ssl/unencrypted_gpo.key ~/geni/gposlice-cred.xml
243$ ./unis_client.py https://monitor.incntre.iu.edu:9000/topologies POST ssl/encrypted_gpo.pem ssl/unencrypted_gpo.key ~/geni/gposlice.unis
244
245Now both slices have a node named "VM", but each user can only see their own resources:
246
247$ ./unis_client.py "https://monitor.incntre.iu.edu:9000/nodes?name=VM&fields=id" GET ssl/kissel.pem ssl/kissel.key ~/geni/ezraslice.unis
248name=VM&fields=id
249Enter PEM pass phrase:
250
251Server Response: 200 OK
252Response data (58 bytes):
253================================================================================
254[
255  {
256    "id": "VM.ezraslice.emulab-net.emulab.net"
257  }
258]
259================================================================================
260
261$ ./unis_client.py "https://monitor.incntre.iu.edu:9000/nodes?name=VM&fields=id" GET ssl/encrypted_gpo.pem ssl/unencrypted_gpo.key
262name=VM&fields=id
263
264Server Response: 200 OK
265Response data (67 bytes):
266================================================================================
267[
268  {
269    "id": "VM.gposlice.pgeni-gpolab-bbn-com.emulab.net"
270  }
271]
272================================================================================
273
274
275If a user tries to push someone else's slice resources:
276
277$ ./unis_client.py https://monitor.incntre.iu.edu:9000/topologies POST ssl/encrypted_gpo.pem ssl/unencrypted_gpo.key ~/geni/ezraslice.unis
278
279
280Server Response: 400 Bad Request
281Response data (77 bytes):
282================================================================================
283{"message": "'GEMINI: one or more network objects is not allowed for user'"}
284
285================================================================================
286
287The check is on the 'properties.geni.slice_uuid' field.  The current GEMINI-AuthZ implementation requires that field as a unique slice identifier.
288
289::Adding a credential::
290
291Now we want to let some other identity (e.g. GEMINI service, portal, etc.) have access to the slice resources associated with the user.  We will call this identity "alice" and then give it access to some of kissel's resources.  We can easily create this identity as a proxy certificate (here valid for 7 days):
292
293$ openssl req -new -config csr.conf -out alice.csr -keyour alice.key
294$ openssl x509 -req -CAcreatesertial -in alice.csr -days 7 -out alice_ID.pem -CA kissel.pem -CAkey kissel.key -extfile csr.conf -extensions v3_proxy
295
296This new certificate is now valid at the UNIS service, meaning the CA chain is verified by the SSL implementation:
297
298$ ./unis_client.py https://monitor.incntre.iu.edu:9000/nodes GET ssl/alice_ID.pem ssl/alice.key
299
300
301Server Response: 403 Forbidden
302Response data (55 bytes):
303================================================================================
304{"message": "'GEMINI: no registered slices for user'"}
305
306================================================================================
307
308...except that alice is not yet authorized to do anything.
309
310Now kissel can create an attribute certificate that says "let alice be a slice admin for my slice" (identified by slice_uuid):
311
312$ creddy --attribute --issuer kissel.pem --key kissel.key --role slice_admin_for_e6037ca6396511e29f72001143e453fe --subject-cert alice_ID.pem --out alice_sa_for_ezraslice_attr.der
313
314(NOTE: the slice_uuid field is in "text" form with hyphens in the manifest, but internally GEMINI-AuthZ uses the "hex" encoding without hyphens.  The ABAC RT0 roles also use the latter form for compactness.)
315
316Now add this credential to UNIS:
317
318$ ./unis_client.py https://monitor.incntre.iu.edu:9000/add_credential POST ssl/alice_ID.pem ssl/alice.key ssl/alice_sa_for_ezraslice_attr.der
319
320Now that the attribute has been added, alice is effectively treated the same as kissel for that slice for 7 days:
321
322$ ./unis_client.py "https://monitor.incntre.iu.edu:9000/nodes?name=VM&fields=id" GET ssl/alice_ID.pem ssl/alice.key
323name=VM&fields=id
324
325Server Response: 200 OK
326Response data (58 bytes):
327================================================================================
328[
329  {
330    "id": "VM.ezraslice.emulab-net.emulab.net"
331  }
332]
333================================================================================
334
335Note that alice will only have permissions to view/modify "ezraslice".  If kissel registers more slices later on, alice will still only be able to see "ezraslice" because of the slice_admin role defined above.  Additional credentials would have to be added for any other slices.
336
337
338