import repository from arizona
[raven.git] / apps / geni / mprepo_geni_libs / sfa / util / geniclient.py
1 ##
2 # This module implements the client-side of the Geni API. Stubs are provided
3 # that convert the supplied parameters to the necessary format and send them
4 # via XMLRPC to a Geni Server.
5 #
6 # TODO: Investigate ways to combine this with existing PLC API?
7 ##
8
9 ### $Id: geniclient.py 14357 2009-07-07 20:49:08Z sapanb $
10 ### $URL: https://svn.planet-lab.org/svn/geniwrapper/trunk/sfa/util/geniclient.py $
11
12 from sfa.trust.gid import *
13 from sfa.trust.credential import *
14 from sfa.util.record import *
15 from sfa.util.sfaticket import SfaTicket
16
17 ##
18 # The GeniClient class provides stubs for executing Geni operations. A given
19 # client object connects to one server. To connect to multiple servers, create
20 # multiple GeniClient objects.
21 #
22 # The Geni protocol uses an HTTPS connection, and the client's side of the
23 # connection uses his private key. Generally, this private key must match the
24 # public key that is containing in the GID that the client is providing for
25 # those functions that take a GID.
26
27 class GeniClient:
28     ##
29     # Create a new GeniClient object.
30     #
31     # @param url is the url of the server
32     # @param key_file = private key file of client
33     # @param cert_file = x.509 cert containing the client's public key. This
34     #      could be a GID certificate, or any x.509 cert.
35     # @param protocol The ORPC protocol to use. Can be "soap" or "xmlrpc"
36
37     def __init__(self, url, key_file, cert_file, protocol="xmlrpc"):
38        self.url = url
39        self.key_file = key_file
40        self.cert_file = cert_file
41
42        if (protocol=="xmlrpc"):
43            import xmlrpcprotocol  
44            self.server = xmlrpcprotocol.get_server(self.url, self.key_file, self.cert_file)
45        elif (protocol=="soap"):
46            import soapprotocol
47            self.server = soapprotocol.get_server(self.url, self.key_file, self.cert_file)
48        else:
49            raise Exception("Attempted use of undefined protocol %s"%protocol)
50
51
52     # -------------------------------------------------------------------------
53     # Registry Interface
54     # -------------------------------------------------------------------------
55
56     ##
57     # Create a new GID. For MAs and SAs that are physically located on the
58     # registry, this allows a owner/operator/PI to create a new GID and have it
59     # signed by his respective authority.
60     #
61     # @param cred credential of caller
62     # @param name hrn for new GID
63     # @param uuid unique identifier for new GID
64     # @param pkey_string public-key string (TODO: why is this a string and not a keypair object?)
65     #
66     # @return a GID object
67
68     def create_gid(self, cred, name, uuid, pkey_string):
69         gid_str = self.server.create_gid(cred.save_to_string(save_parents=True), name, uuid, pkey_string)
70         return GID(string=gid_str)
71
72     ##
73     # Retrieve the GID for an object. This function looks up a record in the
74     # registry and returns the GID of the record if it exists.
75     # TODO: Is this function needed? It's a shortcut for Resolve()
76     #
77     # @param name hrn to look up
78     #
79     # @return a GID object
80
81     def get_gid(self, name):
82        gid_str_list = self.server.get_gid(name)
83        gid_list = []
84        for str in gid_str_list:
85            gid_list.append(GID(string=str))
86        return gid_list
87
88     ##
89     # Get_self_credential a degenerate version of get_credential used by a
90     # client to get his initial credential when he doesn't have one. This is
91     # the same as get_credential(..., cred=None,...).
92     #
93     # The registry ensures that the client is the principal that is named by
94     # (type, name) by comparing the public key in the record's GID to the
95     # private key used to encrypt the client-side of the HTTPS connection. Thus
96     # it is impossible for one principal to retrieve another principal's
97     # credential without having the appropriate private key.
98     #
99     # @param type type of object (user | slice | sa | ma | node
100     # @param name human readable name of object
101     #
102     # @return a credential object
103
104     def get_self_credential(self, type, name):
105         cred_str = self.server.get_self_credential(type, name)
106         return Credential(string = cred_str)
107
108     ##
109     # Retrieve a credential for an object.
110     #
111     # If cred==None, then the behavior reverts to get_self_credential()
112     #
113     # @param cred credential object specifying rights of the caller
114     # @param type type of object (user | slice | sa | ma | node)
115     # @param name human readable name of object
116     #
117     # @return a credental object
118
119     def get_credential(self, cred, type, name):
120         if cred:
121             cred = cred.save_to_string(save_parents=True) 
122         cred_str = self.server.get_credential(cred, type, name)
123         return Credential(string = cred_str)
124
125     ##
126     # List the records in an authority. The objectGID in the supplied credential
127     # should name the authority that will be listed.
128     #
129     # @param cred credential object specifying rights of the caller
130     #
131     # @return list of record objects
132
133     def list(self, cred, auth_hrn):
134         result_dict_list = self.server.list(cred.save_to_string(save_parents=True), auth_hrn)
135         result_rec_list = []
136         for dict in result_dict_list:
137              result_rec_list.append(GeniRecord(dict=dict))
138         return result_rec_list
139
140     ##
141     # Register an object with the registry. In addition to being stored in the
142     # Geni database, the appropriate records will also be created in the
143     # PLC databases.
144     #
145     #
146     #
147     # @param cred credential object specifying rights of the caller
148     # @return record to register
149     #
150     # @return GID object for the newly-registered record
151
152     def register(self, cred, record):
153         gid_str = self.server.register(cred.save_to_string(save_parents=True), record.as_dict())
154         return GID(string = gid_str)
155
156     ##
157     # Remove an object from the registry. If the object represents a PLC object,
158     # then the PLC records will also be removed.
159     #
160     # @param cred credential object specifying rights of the caller
161     # @param type
162     # @param hrn
163
164     def remove(self, cred, type, hrn):
165         result = self.server.remove(cred.save_to_string(save_parents=True), type, hrn)
166         return result
167
168     ##
169     # Resolve an object in the registry. A given HRN may have multiple records
170     # associated with it, and therefore multiple records may be returned. The
171     # caller should check the type fields of the records to find the one that
172     # he is interested in.
173     #
174     # @param cred credential object specifying rights of the caller
175     # @param name human readable name of object
176
177     def resolve(self, cred, name):
178         result_dict_list = self.server.resolve(cred.save_to_string(save_parents=True), name)
179         result_rec_list = []
180         for dict in result_dict_list:
181             if dict['type'] in ['authority']:
182                 result_rec_list.append(AuthorityRecord(dict=dict))
183             elif dict['type'] in ['node']:
184                 result_rec_list.append(NodeRecord(dict=dict))
185             elif dict['type'] in ['slice']:
186                 result_rec_list.append(SliceRecord(dict=dict))
187             elif dict['type'] in ['user']:
188                 result_rec_list.append(UserRecord(dict=dict))
189             else:
190                 result_rec_list.append(GeniRecord(dict=dict))
191         return result_rec_list
192
193     ##
194     # Update an object in the registry. Currently, this only updates the
195     # PLC information associated with the record. The Geni fields (name, type,
196     # GID) are fixed.
197     #
198     #
199     #
200     # @param cred credential object specifying rights of the caller
201     # @param record a record object to be updated
202
203     def update(self, cred, record):
204         result = self.server.update(cred.save_to_string(save_parents=True), record.as_dict())
205         return result
206
207
208     #-------------------------------------------------------------------------
209     # Aggregate Interface
210     #-------------------------------------------------------------------------
211     
212     ## list resources
213     #
214     # @param cred a credential
215     # @param hrn slice hrn
216
217     def get_resources(self, cred, hrn=None):
218         result = self.server.get_resources(cred.save_to_string(save_parents=True), hrn)
219         return result
220
221     def get_aggregates(self, cred, hrn=None):
222         result = self.server.get_resources(cred.save_to_string(save_parents=True), hrn)
223         return result
224
225     ## get policy
226     #
227     # @param cred a credential
228
229     def get_policy(self, cred):
230         result = self.server.get_policy(cred.save_to_string(save_parents=True))
231         return result
232
233     ## create slice
234     #
235     # @param cred a credential
236     # @param rspec resource specification defining how to instantiate the slice
237     
238     def create_slice(self, cred, hrn, rspec):
239         result = self.server.create_slice(cred.save_to_string(save_parents=True), hrn, rspec)
240         return result
241
242
243     ## delete slice
244     #
245     # @param cred a credential
246     # @param hrn slice to delete
247     def delete_slice(self, cred, hrn):
248         result = self.server.delete_slice(cred.save_to_string(save_parents=True), hrn)
249         return result    
250
251     # ------------------------------------------------------------------------
252     # Slice Interface
253     # ------------------------------------------------------------------------
254
255     ##
256     # Start a slice.
257     #
258     # @param cred a credential identifying the caller (callerGID) and the slice
259     #     (objectGID)
260
261     def start_slice(self, cred, hrn):
262         result = self.server.start_slice(cred.save_to_string(save_parents=True), hrn)
263         return result
264
265     ##
266     # Stop a slice.
267     #
268     # @param cred a credential identifying the caller (callerGID) and the slice
269     #     (objectGID)
270
271     def stop_slice(self, cred, hrn):
272         result = self.server.stop_slice(cred.save_to_string(save_parents=True), hrn)
273         return result
274
275     ##
276     # Reset a slice.
277     #
278     # @param cred a credential identifying the caller (callerGID) and the slice
279     #     (objectGID)
280
281     def reset_slice(self, cred, hrn):
282         result = self.server.reset_slice(cred.save_to_string(save_parents=True), hrn)
283         return result
284
285     ##
286     # Delete a slice.
287     #
288     # @param cred a credential identifying the caller (callerGID) and the slice
289     #     (objectGID)
290
291     def delete_slice(self, cred, hrn):
292         result = self.server.delete_slice(cred.save_to_string(save_parents=True), hrn)
293         return result
294
295     ##
296     # List the slices on a component.
297     #
298     # @param cred credential object that authorizes the caller
299     #
300     # @return a list of slice names
301
302     def get_slices(self, cred):
303         result = self.server.get_slices(cred.save_to_string(save_parents=True))
304         return result
305
306     ##
307     # Retrieve a ticket. This operation is currently implemented on the
308     # registry (see SFA, engineering decisions), and is not implemented on
309     # components.
310     #
311     # The ticket is filled in with information from the PLC database. This
312     # information includes resources, and attributes such as user keys and
313     # initscripts.
314     #
315     # @param cred credential object
316     # @param name name of the slice to retrieve a ticket for
317     # @param rspec resource specification dictionary
318     #
319     # @return a ticket object
320
321     def get_ticket(self, cred, name, rspec):
322         ticket_str = self.server.get_ticket(cred.save_to_string(save_parents=True), name, rspec)
323         ticket = SfaTicket(string=ticket_str)
324         return ticket
325
326     ##
327     # Redeem a ticket. This operation is currently implemented on the
328     # component.
329     #
330     # The ticket is submitted to the node manager, and the slice is instantiated
331     # or updated as appropriate.
332     #
333     # TODO: This operation should return a sliver credential and indicate
334     # whether or not the component will accept only sliver credentials, or
335     # will accept both sliver and slice credentials.
336     #
337     # @param ticket a ticket object containing the ticket
338
339     def redeem_ticket(self, ticket):
340         result = self.server.redeem_ticket(ticket.save_to_string(save_parents=True))
341         return result
342
343