1: <?php
2: //----------------------------------------------------------------------
3: // Copyright (c) 2012 Raytheon BBN Technologies
4: //
5: // Permission is hereby granted, free of charge, to any person obtaining
6: // a copy of this software and/or hardware specification (the "Work") to
7: // deal in the Work without restriction, including without limitation the
8: // rights to use, copy, modify, merge, publish, distribute, sublicense,
9: // and/or sell copies of the Work, and to permit persons to whom the Work
10: // is furnished to do so, subject to the following conditions:
11: //
12: // The above copyright notice and this permission notice shall be
13: // included in all copies or substantial portions of the Work.
14: //
15: // THE WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
16: // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17: // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18: // NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
19: // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
20: // WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21: // OUT OF OR IN CONNECTION WITH THE WORK OR THE USE OR OTHER DEALINGS
22: // IN THE WORK.
23: //----------------------------------------------------------------------
24:
25: namespace Overview;
26:
27: /**
28: * This documents the GENI Clearinghouse API
29: * essentials: how methods are invoked, the return values and the
30: * authorization and validation of the calls.
31: */
32: class Overview
33: {
34:
35: /**
36: * The GENI Clearinghouse API consists of a series of services provided
37: * by a series of service providers, namely:
38: <ul>
39: <li>Authorization Service: Provides services for authorizing particular actions by particular users in certain contexts based on their identity, roles and privileges </li>
40: <li>Logging Service: Provides services to log and retrieve tagged information about critical events, e.g. aggregate interactions, slice, member, project modifications, etc.</li>
41: <li>Member Authority: Provides services regarding membership of GENI experimenters including their roles, privileges, account status, credentials, key materials. Note: it is from the Member Authority that experimenters get a GENI account and credentials for interacting with other services. </li>
42: <li>Project Authority: Provides services regarding management of projects and project membership </li>
43: <li>Service Registry: Provides lists of service providers (of the kinds described here) registered within the GENI Clearinghouse </li>
44: <li>Slice Authority: Provides services regarding management of slices and slice membership and credentials </li>
45: </ul>
46: *
47: * A client of a GENI CH API queries the Service Registry for service providers of particular types. The Service Registry is accessed by a known static URL.
48: * The client then forms a message, described under 'Message_Structure', sends it via HTTPS to the given server and receives a response, described under 'Return_Structure'.
49: */
50: function Service_Flow()
51: {
52: }
53:
54: /**
55: * All CH API calls are fundamentally posting S/MIME messages to the appropriate
56: * service URL.
57: * The message should contain a dictionary consisting of key/value pairs.
58: * This pair is mandatory:
59: <ul>
60: <li>"operation" : the name of the API method to be invoked</li>
61: </ul>
62: * The user then adds any name/value pairs required for that particular method
63: * invocation.
64: * <br><br>
65: * For example, to invoke the 'lookup_slice' method,
66: * the user creates a dictionary with the keys 'operation'=>'lookup_slice',
67: * 'slice_id'=> $slice_id.
68: * <br><br>
69: * That dictionary is put in an S/MIME message signed
70: * with the private key of the requestor, JSON encoded and posted via HTTPS to
71: * a 'slice authority' server whose URL
72: * is found in the Clearinghouse Service Registry.
73: * <br><br>
74: * On the server,
75: * the message signature is retrieved and the public key of the user
76: * is used to validate the signature of the message.
77: * <br> <br>
78: * If validated, the message is JSON decoded and the argument dictionary is extracted.
79: * An authorization step is then invoked
80: * to determine if the given user has the privilege to invoke the given
81: * method, possibly in the particular (e.g. slice or project) context.
82: * <br><br>
83: * If the message is not validated, or the invocation is not authorized,
84: * a response is generated as an error message
85: * indicating that reason. If the invocation is authorized, the 'operation' field
86: * in the dictionary of the message is used to dispatch the message appropriately.
87: * The service method then receives the full dictionary as given in the message,
88: * and the function generates a response as documented in these API pages.
89: * <br><br>
90: * The response is then JSON encoded and S/MIME signed with the server's private key
91: * and returned to the requestor via HTTPS.
92: */
93: function Message_Structure()
94: {
95: }
96:
97: /**
98: * The GENI Clearinghouse API contains services whose arguments are often one of these types:
99: * <br><br>
100: * <b>Context</b>: Methods that call for a "Context" and "ContextID"
101: * argument reflect the relationship of a principal to a particular object.
102: * Specifically, privileges of GENI members may be provided and tested on the granularity of a context.
103: * For some context_types, there is a specific context_id required, indicating a context of a particular object (e.g. a specific slice or project). Other context types, as noted, are not applied to a particular context_id. These are the context_types recognized by GENI:
104: <ul>
105: <li>PROJECT=1: Refers to a specific project and takes a context_id (i.e. the project's UUID) </li>
106: <li>SLICE=2: Refers to a specific slice and takes a context_id (i.e. the slice's UUID) </li>
107: <li>RESOURCE=3: Refers to the ability to take actions that manage resources (e.g. creating a project) </li>
108: <li>SERVICE=4: Refers to the ability to change the set of services provided by the Clearinghouse (those in the Service Registry, e.g.) </li>
109: <li>MEMBER=5: Refers to the abilitiy to change the account information about GENI members </li>
110: </ul>
111: *<br><br>
112: * <b>Role_Types</b>: Calls specifying a 'role_type' require an indication of the role a given member plays within a group (e.g. a slice or project).
113: * Privileges are often allotted to members based on their role within a group.
114: * The set of roles recognized in the GENI CH API are:
115: <ul>
116: <li>LEAD=1: The lead or owner of a project or slice. There can be only one of these per project/slice. They are the person responsible and principal point-of-contact regarding all activity on that project or slice </li>
117: <li>ADMIN=2: A person with privileges to change attributes or privileges of other members of a group, but not the lead. </li>
118: <li>MEMBER=3: A normal member of a group with privileges to normal (typically read and write) operations on entities managed by that group. </li>
119: <li>AUDITOR=4: A member of the group with read-only privileges. </li>
120: </ul>
121: *<br><br>
122: * <b>Attributes</b>: Many objects are tagged with dictionaries of name/value pairs for later query (by explicit match on a single attribute, or by "AND" of a dictionary of attributes or by "OR" of "AND" of a list of dictionaries of attributes)
123: */
124: function Argument_Types()
125: {
126: }
127:
128: /**
129: * All method calls from the GENI CH API return a dictionary
130: * representing a 3-tuple of values:
131: <ul>
132: <li>"code" : the error code, if any (0 if no error) </li>
133: <li>"value" : the result value, only valid if "code" is 0. This is the value indicated as the 'return' for all documented functions </li>
134: <li>"output" : the error detail (typically a descriptive string) associated with an invocation error (i.e. error is not 0) </li>
135: </ul>
136: */
137: function Return_Structure()
138: {
139: }
140:
141:
142: }
143:
144:
145: ?>
146: