1: <?php
2:
3: namespace Authorization_Service;
4:
5: //----------------------------------------------------------------------
6: // Copyright (c) 2012 Raytheon BBN Technologies
7: //
8: // Permission is hereby granted, free of charge, to any person obtaining
9: // a copy of this software and/or hardware specification (the "Work") to
10: // deal in the Work without restriction, including without limitation the
11: // rights to use, copy, modify, merge, publish, distribute, sublicense,
12: // and/or sell copies of the Work, and to permit persons to whom the Work
13: // is furnished to do so, subject to the following conditions:
14: //
15: // The above copyright notice and this permission notice shall be
16: // included in all copies or substantial portions of the Work.
17: //
18: // THE WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
19: // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
20: // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
21: // NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
22: // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
23: // WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24: // OUT OF OR IN CONNECTION WITH THE WORK OR THE USE OR OTHER DEALINGS
25: // IN THE WORK.
26: //----------------------------------------------------------------------
27:
28: /**
29: * GENI Clearinghouse Authorization Service (AZ) controller interface
30: *<br><br>
31: * The Authorization Service allows for storing of two kinds of credentials:
32: * <ul>
33: * <li> Attributes (signed assertions that principal P has attribute A,
34: * possibly in context C) </li>
35: * <li> Policies (signed statements that principals with attribute A
36: * possibly in context X have a given privilege) </li>
37: * </ul>
38: * <br><br>
39: * Note that the current clearinghouse implementation refers to this service as the
40: * "Credential Store', offered by 'cs_controller.php'. This is intended to change
41: * to the authorization Service and 'authz_controller.php' in upcoming releases. But the
42: * client interface will be unaffected by this name change.
43: * <br><br>
44: * Supports 4 'write' interfaces:
45: <ul>
46: <li> id <= create_assertion(principal, attribute, context_type, context) </li>
47: <li> id <= create_policy(attribute, context_type, privilege) </li>
48: <li> success/failure <= renew_assertion(id) </li>
49: <li> success/failure <= delete_policy(id); </li>
50: </ul>
51: * <br><br>
52: * Supports 4 'read' interfaces:
53: <ul>
54: <li> assertions <= query_assertions(principal, context_type, context) </li>
55: <li> policies <= query_policies(); </li>
56: <li> success/failure <= request_authorization(principal, action, context_type, context) </li>
57: <li> permissions <= get_permissions(principal) </li>
58: </ul>
59: **/
60: class Authorization_Service {
61:
62: /**
63: * Create an assertion of a given principal having a given attribute (role) with respect to a given context.
64: * @param dict $args_dict Dictionary containing name/value pairs:
65: <ul>
66: <li>"principal" : UUID of principal about whom assertion is made</li>
67: <li>"attribute" : id/index of attribute type</li>
68: <li>"context_type" : type of context in which assertion holds</li>
69: <li>"context" : UUID of context (if any) for which assertion holds</li>
70: </ul>
71: * @return string ID of assertion
72: */
73: function create_assertion($args_dict)
74: {
75: }
76:
77: /**
78: * Create a policy and store in AZ
79: * @param dict $args_dict Dictionary containing name/value pairs:
80: <ul>
81: <li>"operation" : name of this method ("create_policy")</li>
82: <li>"attribute" : id/index of attribute type</li>
83: <li>"context_type" : type of context in which attribute holds</li>
84: <li>"privilege" " id/index of privilege type</li>
85: </ul>
86: * @return string ID of policy
87: */
88: function create_policy($args_dict)
89: {
90: }
91:
92: /**
93: * Delete a given assertion with given ID
94: * @param dict $args_dict Dictionary containing name/value pairs:
95: <ul>
96: <li>"operation" : name of this method ("delete_assertion")</li>
97: <li>"id" - ID of assertion to be deleted</li>
98: </ul>
99: * @return boolean Success / Failure
100: */
101: function delete_assertion($args_dict)
102: {
103: }
104:
105: /**
106: * Delete a given policy of given ID
107: * @param dict $args_dict Dictionary containing name/value pairs:
108: <ul>
109: <li>"operation" : name of this method ("delete_policy")</li>
110: <li>"id" : ID of assertion to be renewed</li>
111: </ul>
112: * @return boolean Success / Failure
113: */
114: function delete_policy($args_dict)
115: {
116: }
117:
118: /**
119: * Renew a given assertion with given ID
120: * @param dict $args_dict Dictionary containing name/value pairs:
121: <ul>
122: <li>"operation" : name of this method ("renew_assertion")</li>
123: <li>"id" : ID of assertion to be renewed</li>
124: </ul>
125: * @return boolean Success / Failure
126: */
127: function renew_assertion($args_dict)
128: {
129: }
130:
131: /**
132: * *** NOT IMPLEMENTED! ***
133: * Renew a given policy with given ID
134: * @param dict $args_dict Dictionary containing name/value pairs:
135: <ul>
136: <li>"operation" : name of this method ("renew_assertion")</li>
137: <li>"id" : ID of policy to be renewed</li>
138: </ul>
139: * @return boolean Success / Failure
140: */
141: function renew_policy($args_dict)
142: {
143: }
144:
145: /**
146: * Return a list of assertions for a given principal
147: * possibly in a given context
148: * @param dict $args_dict Dictionary containing name/value pairs:
149: <ul>
150: <li>"operation" : name of this method ("query_assertions")</li>
151: <li>"principal" : UUID of principal</li>
152: <li>"context_type" : type of context </li>
153: <li>"context" : UUID of context (if any)n</li>
154: </ul>
155: * @return array List of assertions matching given query
156: */
157: function query_assertions($args_dict)
158: {
159: }
160:
161: /**
162: * Return a list of all policies in authorization service's credential store
163: * @param dict $args_dict Dictionary containing name/value pairs:
164: <ul>
165: <li>"operation" : name of this method ("query_policies")</li>
166: </ul>
167: * @return array List of all policies in AZ's credential store
168: */
169: function query_policies($args_dict)
170: {
171: }
172:
173: /**
174: * Return whether a given principal is allowed to take a given
175: * action in a given context.
176: * @param dict $args_dict Dictionary containing name/value pairs:
177: <ul>
178: <li>"operation" : name of this method ("query_policies")</li>
179: <li>"principal" : UUID of principal about whom authorization is requested</li>
180: <li>"action" : name of action for which authorization is requested</li>
181: <li>"context_type" : context type about which authorization is requested</li>
182: <li>"context" " context_id about which authorization is requested [optional]</li>
183: </ul>
184: * @return boolean Success / Failure of authorization request
185: */
186: function request_authorization($args_dict)
187: {
188: }
189:
190: /**
191: * Get the permissions (allowed actions) for a given principal
192: * @param dict $args_dict Dictionary containing name/value pairs:
193: <ul>
194: <li>"operation" : name of this method ("query_policies")</li>
195: <li>"principal" : UUID of principal about which actions are being requested</li>
196: </ul>
197: * @return array List of action, context_type, context_id tuples for which principal has authorization
198: */
199: function get_permissions($args_dict)
200: {
201: }
202:
203: /**
204: * Get the version of the API of this particular service provider
205: * @param dict $args_dict Dictionary containing 'operation' argument
206: * @return number Version of API of this particular service provider
207: */
208: function get_version($args_dict)
209: {
210: }
211:
212: }
213:
214:
215: ?>
216:
217: