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