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 Member_Authority;
 26: 
 27: 
 28: /**
 29:  * GENI Clearinghouse Member Authority (MA) controller interface
 30:  * <br><br>
 31:  * The MA maintains a set of members and their UUIDs and their attributes and associated query mechanisms.
 32:  * The MA maintains a set of SSL keys and certs, both 'inside' and 'outside' for given users.
 33:  * Additionally, the MA maintains a mapping of members to the client tools (e.g. the GENI Portal) that the member has authorized to speak on his/her behalf.
 34:  * Finally, the MA maintains a set of SSH keys for a given member for passing to resources as needed.
 35:  * <br><br>
 36:  * Supports these methods:
 37: <ul>
 38: <li>success <= register_ssh_key(member_id, ssh_filename, ssh_description, ssh_public_key, [ssh_private_key])</li>
 39: <li>[id, member_id, filename, description, public_key, private_key]* <= lookup_ssh_keys(member_id)</li>
 40: <li>success <= update_ssh_key(member_id, ssh_key_id, ssh_filename, ssh_description)</li>
 41: <li>success <= delete_ssh_key(member_id, ssh_key_id)</li>
 42: <li>[private_key, certificate]* <= lookup_keys_and_certs(member_id)</li>
 43: <li>member_id <= create_account(attributes)</li>
 44: <li>[client_name, client_urn]* <= ma_list_clients()</li>
 45: <li>[client_name, client_urn]* <= ma_list_authorized_clients(member_id)</li>
 46: <li>success <= ma_authorize_client(member_id, client_urn, authorize_sense)</li>
 47: <li>[member_id]* <= lookup_members(attributes) </li>
 48: <li>[member_id, [name value self_asserted]*] <= lookup_member_by_id(member_id)</li>
 49: <li>success <= add_member_privilege(member_id, privilege_id)</li>
 50: <li>success <= revoke_member_privilege(member_id, privilege_id)</li>
 51: </ul>
 52: <br><br>
 53: Future (i.e. not yet available) methods include:
 54: <ul>
 55: <li>upload_ssl_keys </li>
 56: <li>revoke_certificate</li>
 57: </ul>
 58:  */
 59: class Member_Authority {
 60: 
 61: /**
 62:  * Register SSH public key with given user
 63:  *
 64:  * @param dict $args_dict Dictionary containing name/value pairs:
 65: <ul>
 66:    <li>"operation" : name of this method ("register_ssh_key")</li>
 67:    <li>"member_id" : ID of member about whom SSH key is to be registered</li>
 68:    <li>"ssh_filename" : filename containing public SSH key (upload case)</li>
 69:    <li>"ssh_description" : Description of given SSH key </li>
 70:    <li>"ssh_public_key" : SSH public key value</li>
 71:    <li>"ssh_private_key" : SSH private key value (optional: generate key pair case)</li>
 72: </ul>
 73:  * @return boolean Success/Fail
 74:  *   
 75:  */
 76: function register_ssh_key($args_dict)
 77: {
 78: }
 79: 
 80: /**
 81:  * Return all SSH keys associated with given member
 82:  *
 83:  * @param dict $args_dict Dictionary containing name/value pairs:
 84: <ul>
 85:    <li>"operation" : name of this method ("lookup_ssh_keys")</li>
 86:    <li>"member_id" : ID of member about whom SSH key is to be registered</li>
 87: </ul>
 88:  * @return array List of SSH key info (member_id, filename, description, public_key, private_key) for given member
 89:  *   
 90:  */
 91: function lookup_ssh_keys($args_dict)
 92: {
 93: }
 94: 
 95: /**
 96:  * Update key pair associated with member
 97:  *
 98:  * @param dict $args_dict Dictionary containing name/value pairs:
 99: <ul>
100:    <li>"operation" : name of this method ("update_ssh_key")</li>
101:    <li>"member_id" : ID of member about whom to update SSH key</li>
102:    <li>"ssh_key_id" : ID of SSH key pair for member
103:    <li>"ssh_filename" : filename containing public SSH key </li>
104:    <li>"ssh_description" : New description of SSH key pair for member
105: </ul>
106:  * @return boolean Success/Failure
107:  */
108: function update_ssh_key($args_dict)
109: {
110: }
111: 
112: /**
113:  * Remove key pair associated with member
114:  *
115:  * @param dict $args_dict Dictionary containing name/value pairs:
116: <ul>
117:    <li>"operation" : name of this method ("delete_ssh_key")</li>
118:    <li>"member_id" : ID of member about whom to delete ssh key pair</li>
119:    <li>"ssh_key_id" : ID of SSH key pair for member
120: </ul>
121:  * @return boolean Success/Failure
122:  */
123: function delete_ssh_key($args_dict)
124: {
125: }
126: 
127: /**
128:  * Lookup inside keys/certs associated with a user UUID.
129:  *
130:  * @param dict $args_dict Dictionary containing name/value pairs:
131: <ul>
132:    <li>"operation" : name of this method ("lookup_keys_and_certs")</li>
133:    <li>"member_id" : ID of member about whom inside keys and certs are desired</li>
134: </ul>
135:  * @return Dictionary containing a private key and certificate for given member
136:  */
137: function lookup_keys_and_certs($args_dict)
138: {
139: }
140: 
141: /**
142:  * Create new user account with given attributes.
143:  *    Required attributes: email_address, first_name, last_name, telephone_number
144:  * @param dict $args_dict Dictionary containing name/value pairs:
145: <ul>
146:    <li>"operation" : name of this method ("create_account")</li>
147:    <li>"attributes" : Dictionary of attributes (required keys: email_address, first_name, last_name, telephone_number) of member account to be created.</li>
148: </ul>
149:  * @return UUID of newly created member
150:  */
151: function create_account($args_dict)
152: {
153: }
154: 
155: /**
156:  * Get all client tools registered with the MA as potentially authorized for use by members
157:  * @param dict $args_dict Dictionary containing name/value pairs:
158: <ul>
159:    <li>"operation" : name of this method ("ma_list_clients")</li>
160: </ul>
161:  * @return List of (name => URN) pairs of registered tools
162:  */
163: function ma_list_clients($args_dict)
164: {
165: }
166: 
167: /**
168:  * Get all client tools registered with the MA for given user
169:  * @param dict $args_dict Dictionary containing name/value pairs:
170: <ul>
171:    <li>"operation" : name of this method ("ma_list_authorized_clients")</li>
172:    <li>"member_id" : UUID of given member for whom to return registered client tools</li>
173: </ul>
174:  * @return List of (name => URN) pairs of registered tools for given member
175:  */
176: function ma_list_authorized_clients($args_dict)
177: {
178: }
179: 
180: /**
181:  * Authorize/Deauthorize given tool for use by given member
182:  * @param dict $args_dict Dictionary containing name/value pairs:
183: <ul>
184:    <li>"operation" : name of this method ("ma_authorize_client")</li>
185:    <li>"member_id" : UUID of given member for whom to return registered client tools</li>
186:    <li>"client_urn" : URN of given client tool</li>
187:    <li>"authorize_sense" : True for authorize, False for deauthorize</li>
188: </ul>
189:  * @return boolean Success/Failure
190:  */
191: function ma_authorize_client($args_dict)
192: {
193: }
194: 
195: /**
196:  * Return list of members satisfying the 'and' of a provided set of name/value attributes
197:  * @param dict $args_dict Dictionary containing name/value pairs:
198: <ul>
199:    <li>"operation" : name of this method ("looukp_members")</li>
200:    <li>"attributes" : Dictionary of name/value pairs the 'and' of which is applied to query for registered members</li>
201: </ul>
202:  * @return List of UUIDs of members registered with MA satisfying attributes
203:  */
204: function lookup_members($args_dict)
205: {
206: }
207: 
208: /**
209:  * Return name/value attribute information about given member by UUID
210:  * @param dict $args_dict Dictionary containing name/value pairs:
211: <ul>
212:    <li>"operation" : name of this method ("looukp_member_by_id")</li>
213:    <li>"member_id" : UUID of member about whom information is requested</li>
214: </ul>
215:  * @return Dictionary of name/value pairs associated with member
216:  */
217: function lookup_member_by_id($args_dict)
218: {
219: }
220: 
221: /**
222:  * Add new privilege to given member
223:  * @param dict $args_dict Dictionary containing name/value pairs:
224: <ul>
225:    <li>"operation" : name of this method ("add_member_privilege")</li>
226:    <li>"member_id" : UUID of member about whom to add privilege</li>
227:    <li>"privilege_id" : Type of privilege added to member</li>
228: </ul>
229:  * @return boolean Success/Failure
230:  */
231: function add_member_privilege($args_dict)
232: {
233: }
234: 
235: /**
236:  * Revoke privilege to given member
237:  * @param dict $args_dict Dictionary containing name/value pairs:
238: <ul>
239:    <li>"operation" : name of this method ("revoke_member_privilege")</li>
240:    <li>"member_id" : UUID of member about whom to remove privilege</li>
241:    <li>"privilege_id" : Type of privilege removed from member</li>
242: </ul>
243:  * @return boolean Success/Failure
244:  */
245: function revoke_member_privilege($args_dict)
246: {
247: }
248: 
249: /**
250:  * Get the version of the API of this particular service provider
251:  * @param dict $args_dict Dictionary containing 'operation' argument
252:  * @return number Version of API of this particular service provider
253:  */
254: function get_version($args_dict)
255: {
256: }
257: 
258: 
259: ?>
260: