Client SDK Version 1.8.0
Ionic Security client SDK for Python users
Public Member Functions | List of all members
ionicsdk.agent.Agent Class Reference

Agent class performs all client/server communication with Ionic.com. More...

Inheritance diagram for ionicsdk.agent.Agent:
ionicsdk.services.AgentKeyServicesBase

Public Member Functions

def __init__ (self, agentconfig=None, profilepersistor=None, loadprofiles=True, cloneagent=None, profilemanager=None)
 An Agent object can be initialized with different profile persistors and a config object, or defaults. More...
 
def getLastServerResponse (self)
 Return the Server Response object from the last Agent call. More...
 
def getprofilemanager (self)
 Get the profile manager object for this agent. More...
 
def hasactiveprofile (self)
 (DEPRECATED) Determine if any device profile is active. More...
 
def setactiveprofile (self, deviceid)
 (DEPRECATED) Set the current device profile of the agent. More...
 
def getactiveprofile (self)
 (DEPRECATED) Get the current device profile of the agent. More...
 
def hasanyprofiles (self)
 (DEPRECATED) Determine if any device profiles are loaded. More...
 
def getallprofiles (self)
 (DEPRECATED) Get all available device profiles. More...
 
def addprofile (self, deviceprofile, makeactive=False)
 (DEPRECATED) Add a device profile to the agent device profile collection. More...
 
def removeprofile (self, deviceid)
 (DEPRECATED) Remove a device profile from the agent device profile list. More...
 
def updateprofile (self, deviceid=None, knsProviderUrl=None)
 Finds the deviceId (or uses the active profile), gets the current KNS information for the profile keyspace, and then updates the profile (and active profile if needed). More...
 
def getprofileforkeyid (self, keyid)
 (DEPRECATED) Determine which device profile is associated with the provided key ID. More...
 
def getmetadata (self)
 Get metadata dictionary that will be included with requests from this agent. More...
 
def setmetadata (self, metadatadict)
 Set metadata dictionary to be included with requests from this agent. More...
 
def loadprofiles (self, persistor)
 (DEPRECATED) Load device profiles using the provided profile persistor. More...
 
def saveprofiles (self, persistor)
 (DEPRECATED) Save device profiles using the specified profile persistor. More...
 
def createdevice (self, server, etag, token, uidauth, rsa_pub_key_base64, profilename='')
 Creates (registers) a device with Ionic.com. More...
 
def createkey (self, attributes=None, metadata=None, mutableAttributes=None)
 Creates a single protection key with attributes through Ionic.com. More...
 
def createkeys (self, keycount, attributes=None, metadata=None, mutableAttributes=None)
 Creates protection keys through Ionic.com. More...
 
def getkey (self, keyid, metadata=None)
 Gets a single protection key from Ionic.com. More...
 
def getkeys (self, keyids, metadata=None)
 Gets protection keys from Ionic.com. More...
 
def getkeys2 (self, keyids, externalkeyids, metadata=None)
 Gets protection keys from Ionic.com. More...
 
def updatekey (self, updateKeyData, metadata=None)
 Updates the mutable portion of the attributes on a protection key at Ionic.com. More...
 
def updatekeys (self, KeyDataArray, metadata=None)
 Updates the mutable portion of the attributes on a list of protection keys at Ionic.com. More...
 
def logmessage (self, msgtype, datajson, metadata=None)
 Logs a single messages to Ionic.com. More...
 
def logmessages (self, msgtypes, datajsons, metadata=None)
 Logs one or more messages to Ionic.com. More...
 
def createidassertion (self, foruri, nonce, metadata=None)
 Creates an identity assertion issued by an Ionic Key Server. More...
 
def getresource (self, resourceid, args=None, metadata=None)
 Gets a generic resource from Ionic.com. More...
 
def getresources (self, resourcelist, metadata=None)
 Gets one or more generic resource(s) from Ionic.com. More...
 
def getkeyspace (self, keyspace, knsProviderUrl=None)
 Gets keyspace information from Ionic.com. More...
 

Detailed Description

Agent class performs all client/server communication with Ionic.com.

Constructor & Destructor Documentation

◆ __init__()

def ionicsdk.agent.Agent.__init__ (   self,
  agentconfig = None,
  profilepersistor = None,
  loadprofiles = True,
  cloneagent = None,
  profilemanager = None 
)

An Agent object can be initialized with different profile persistors and a config object, or defaults.

By default an Agent will load profiles from the platform- specific device profile persistor (if one exists for the platform, otherwise an AGENT_NO_PROFILE_PERSISTOR IonicException may be thrown if no other persistor is specified). Loading can be disabled, or a DeviceProfilePersistorPlaintextFile, DeviceProfilePersistorPasswordFile, or DeviceProfilePersistorAesGcmFile can be used to load profiles from a file.

An AgentConfig object or configuration file can specify network communication parameters.

Parameters
agentconfig(AgentConfig, optional): An AgentConfig object can specify network configuration parameters.
profilepersistor(DeviceProfilePersistorBase, optional): A device profile persistor. If unspecified or None, will use platform default which will be shared across all ionic-enabled applications. Subclasses are available to load profiles from plaintext, passworded, or encrypted files.
loadprofiles(bool, optional): Set to false to prevent loading of profiles. Profiles must be added or loaded using Agent.*profile[s] methods before using the Agent object for network communication.
cloneagent(Agent, optional): If present, this overrides the other parameters and an Agent is created by copying the one passed. This is useful in a multithread environment.
profilemanager(ProfileManager, optional): If present, this will not use the persistor and instead copy profiles and current active profile from the argument into the new Agent.

Member Function Documentation

◆ addprofile()

def ionicsdk.agent.Agent.addprofile (   self,
  deviceprofile,
  makeactive = False 
)

(DEPRECATED) Add a device profile to the agent device profile collection.

Deprecated:
This function has moved to ProfileManager, accessible through getprofilemanager(). Time for removal is TBD.
Parameters
deviceprofile(DeviceProfile): The device profile object.
makeactive(bool, optional): If true, then this profile will be set as the active profile (default: False).
Returns
None, raises an exception on errors

◆ createdevice()

def ionicsdk.agent.Agent.createdevice (   self,
  server,
  etag,
  token,
  uidauth,
  rsa_pub_key_base64,
  profilename = '' 
)

Creates (registers) a device with Ionic.com.

This method makes an HTTP call to Ionic.com to register a device.

It is the responsibility of the caller to save this new profile to a persistent store by calling Agent.saveprofiles() or by saving it in another way of their choice.

Parameters
server(string): The server to be used for the device registration call.
etag(string): The ETag (enrollment tag.
token(string): The token.
uidauth(string): The UIDAuth.
rsa_pub_key_base64(string): The Base64 encoded RSA public key belonging to the EI (Enrollment Infrastructure).
profilename(string, optional): Device profile name to be used for the device being created (default: '').
Returns
A device profile

◆ createidassertion()

def ionicsdk.agent.Agent.createidassertion (   self,
  foruri,
  nonce,
  metadata = None 
)

Creates an identity assertion issued by an Ionic Key Server.

This method makes an HTTP call to Ionic.com to request the creation of an identity assertion by an Ionic Key Server. This assertion is useful for proving that the machine which requested the assertion is in fact a registered device in the Ionic Key Server. The Ionic Key Server which creates the assertion is the one associated with the currently active profile of this agent object (see Agent.getactiveprofile()).

Parameters
foruri(string): The URI for the assertion.
nonce(string): The nonce used for this assertion.
metadata(MetadataDict, optional): The metadata properties to send along with the HTTP request.
Returns
A string containing the assertion

◆ createkey()

def ionicsdk.agent.Agent.createkey (   self,
  attributes = None,
  metadata = None,
  mutableAttributes = None 
)

Creates a single protection key with attributes through Ionic.com.

This method makes an HTTP call to Ionic.com to create a protection key with attributes.

Parameters
attributes(KeyAttributesDict, optional): The protection key attributes to use for creating the protection key.
metadata(MetadataDict, optional): The metadata properties to send along with the HTTP request.
mutableAttributes(KeyAttributesDict, optional): The protection key mutable attributes to use for creating the protection key.
Returns
A KeyData object with the newly created protection key from Ionic.com.

Reimplemented from ionicsdk.services.AgentKeyServicesBase.

◆ createkeys()

def ionicsdk.agent.Agent.createkeys (   self,
  keycount,
  attributes = None,
  metadata = None,
  mutableAttributes = None 
)

Creates protection keys through Ionic.com.

This method makes an HTTP call to Ionic.com to create protection keys.

NOTE: please limit to 1,000 keys per request, otherwise the server will return an error.

Parameters
keycount(int): The number of keys to create.
attributes(KeyAttributesDict, optional): The protection key attributes to use for creating the protection keys.
metadata(MetadataDict, optional): The metadata properties to send along with the HTTP request.
mutableAttributes(KeyAttributesDict, optional): The protection key mutable attributes to use for creating the protection key.
Returns
The KeyDataList of newly created protection keys from Ionic.com.

Reimplemented from ionicsdk.services.AgentKeyServicesBase.

◆ getactiveprofile()

def ionicsdk.agent.Agent.getactiveprofile (   self)

(DEPRECATED) Get the current device profile of the agent.

Deprecated:
This function has moved to ProfileManager, accessible through getprofilemanager(). Time for removal is TBD.
Returns
Returns the active device profile object. If no active profile is set, then None will be returned. You can also call Agent.hasactiveprofile() to determine if there is an active profile.

Reimplemented from ionicsdk.services.AgentKeyServicesBase.

◆ getallprofiles()

def ionicsdk.agent.Agent.getallprofiles (   self)

(DEPRECATED) Get all available device profiles.

Deprecated:
This function has moved to ProfileManager, accessible through getprofilemanager(). Time for removal is TBD.
Returns
Returns a DeviceProfileList (subclass of list) of all device profile objects.

◆ getkey()

def ionicsdk.agent.Agent.getkey (   self,
  keyid,
  metadata = None 
)

Gets a single protection key from Ionic.com.

This method makes an HTTP call to Ionic.com to get a protection key.

Parameters
keyid(string): The protection key ID to fetch.
metadata(MetadataDict, optional): The metadata properties to send along with the HTTP request.
Returns
A KeyData object containing the requested key.

Reimplemented from ionicsdk.services.AgentKeyServicesBase.

◆ getkeys()

def ionicsdk.agent.Agent.getkeys (   self,
  keyids,
  metadata = None 
)

Gets protection keys from Ionic.com.

This method makes an HTTP call to Ionic.com to get protection keys.

NOTE: please limit to 1,000 keys per request, otherwise the server will return an error.

Parameters
keyids(string): The list of protection key IDs to fetch.
metadata(MetadataDict, optional): The metadata properties to send along with the HTTP request.
Returns
A list of keys that were successfully retrieved. It is important to note that even if the function succeeds, it does NOT mean that any or all of the requested keys were provided. The caller can iterate through the response object and determine which keys were returned by looking at the key ID property (KeyData.id).

Reimplemented from ionicsdk.services.AgentKeyServicesBase.

◆ getkeys2()

def ionicsdk.agent.Agent.getkeys2 (   self,
  keyids,
  externalkeyids,
  metadata = None 
)

Gets protection keys from Ionic.com.

This method makes an HTTP call to Ionic.com to get protection keys.

NOTE: please limit to 1,000 keys per request, otherwise the server will return an error.

Parameters
keyids(string): The list of protection key IDs to fetch.
externalkeyids(string): Alternate list of external ids of keys to fetch. External ids reference keys with external ids in their AttributeMap.
metadata(MetadataDict, optional): The metadata properties to send along with the HTTP request.
Returns
A tuple containing:
  • A list of keys that were successfully retrieved. It is important to note that even if the function succeeds, it does NOT mean that any or all of the requested keys were provided. The caller can iterate through the response object and determine which keys were returned by looking at the key ID property (KeyData.id).
  • A list of Query results. Each Query Result contains the external key id and either a list of matching key ids (ionic) or an error code and error message. If a key just isn't found, there will be no Query result for it.
  • A list of per Key Errors. (Almost always empty) Each Error result is generated when an error is generated from a specific key id such as a privilege error. Each Error is a dict containing a key id, a client error code, a server error code, and a server message

◆ getkeyspace()

def ionicsdk.agent.Agent.getkeyspace (   self,
  keyspace,
  knsProviderUrl = None 
)

Gets keyspace information from Ionic.com.

This method makes an HTTP call to Ionic.com to request keyspace information.

Parameters
keyspace(unicode): Keyspace string
knsProviderUrl(unicode): Optional url for an alternate KNS provider, defaults to https://api.ionic.com
Returns
KeyspaceResponse containing the Fully Qualified Domain Name (fqdn), the tenant ID (tenantId), the enrollment url (enrollUrl) and optionally an api url (apiUrl).

◆ getLastServerResponse()

def ionicsdk.agent.Agent.getLastServerResponse (   self)

Return the Server Response object from the last Agent call.

Returns
A valid ServerResponse object or None if no server calls have been made yet.

◆ getmetadata()

def ionicsdk.agent.Agent.getmetadata (   self)

Get metadata dictionary that will be included with requests from this agent.

Returns
The metadata dictionary as a Python MetadataDict instance

◆ getprofileforkeyid()

def ionicsdk.agent.Agent.getprofileforkeyid (   self,
  keyid 
)

(DEPRECATED) Determine which device profile is associated with the provided key ID.

Deprecated:
This function has moved to ProfileManager, accessible through getprofilemanager(). Time for removal is TBD.
Parameters
keyid(string): The key ID for which to retrieve the associated device profile.
Returns
The DeviceProfile associated with the provided key ID, or None if not found.

◆ getprofilemanager()

def ionicsdk.agent.Agent.getprofilemanager (   self)

Get the profile manager object for this agent.

Returns
A profile manager object that can be modified to change the agents behavior.

◆ getresource()

def ionicsdk.agent.Agent.getresource (   self,
  resourceid,
  args = None,
  metadata = None 
)

Gets a generic resource from Ionic.com.

This method makes an HTTP call to Ionic.com to request a generic resource.

Parameters
resourceid(string): The resource/rpc ID string for this request.
args(string, optional): The optional arguments string for this request.
metadata(MetadataDict, optional): The metadata properties for this request.
Returns
A ResourceResponse data object.

◆ getresources()

def ionicsdk.agent.Agent.getresources (   self,
  resourcelist,
  metadata = None 
)

Gets one or more generic resource(s) from Ionic.com.

This method makes an HTTP call to Ionic.com to request generic resource(s).

Parameters
resourcelist(list[ResourceRequest]): A list of ResourceResquest Objects filled in with resource IDs and args.
metadata(MetadataDict, optional): The metadata properties to send along with the HTTP request.
Returns
ResourceResponseList containing ResourceResponse data objects.

◆ hasactiveprofile()

def ionicsdk.agent.Agent.hasactiveprofile (   self)

(DEPRECATED) Determine if any device profile is active.

Deprecated:
This function has moved to ProfileManager, accessible through getprofilemanager(). Time for removal is TBD.
Returns
True if an active profile is loaded, False otherwise

Reimplemented from ionicsdk.services.AgentKeyServicesBase.

◆ hasanyprofiles()

def ionicsdk.agent.Agent.hasanyprofiles (   self)

(DEPRECATED) Determine if any device profiles are loaded.

Deprecated:
This function has moved to ProfileManager, accessible through getprofilemanager(). Time for removal is TBD.
Returns
True if an any profile is loaded, False otherwise

◆ loadprofiles()

def ionicsdk.agent.Agent.loadprofiles (   self,
  persistor 
)

(DEPRECATED) Load device profiles using the provided profile persistor.

Attempts to load device profiles using the specified profile persistor.

If loading is successful, all existing profiles associated with the agent will be discarded in favor of the newly loaded profiles. The active profile provided by the persistor will replace the previous active profile (if any). It is also possible that the persistor does not provide an active profile, in which case the agent object will be left without an active profile.

If loading is not successful, then no changes are made to the state of the agent.

Deprecated:
This function has moved to ProfileManager, accessible through getprofilemanager(). Time for removal is TBD.
Parameters
persistor(DeviceProfilePersistorBase): The device profile persistor.
Returns
None, raises an exception on errors

◆ logmessage()

def ionicsdk.agent.Agent.logmessage (   self,
  msgtype,
  datajson,
  metadata = None 
)

Logs a single messages to Ionic.com.

This method makes an HTTP call to Ionic.com to post a single log message.

Parameters
msgtype(string): The message type string.
datajson(string): The message data in JSON format.
metadata(MetadataDict, optional): The metadata properties to send along with the HTTP request.
Returns
None

◆ logmessages()

def ionicsdk.agent.Agent.logmessages (   self,
  msgtypes,
  datajsons,
  metadata = None 
)

Logs one or more messages to Ionic.com.

This method makes an HTTP call to Ionic.com to post one or more log messages.

Parameters
msgtypes(list[string]): The list of message type strings.
datajsons(list[string]): The list of message data strings in JSON format.
metadata(MetadataDict, optional): The metadata properties to send along with the HTTP request.
Returns
None

◆ removeprofile()

def ionicsdk.agent.Agent.removeprofile (   self,
  deviceid 
)

(DEPRECATED) Remove a device profile from the agent device profile list.

Deprecated:
This function has moved to ProfileManager, accessible through getprofilemanager(). Time for removal is TBD.
Parameters
deviceid(string): The device id of the profile to remove.
Returns
None, raises an exception on errors

◆ saveprofiles()

def ionicsdk.agent.Agent.saveprofiles (   self,
  persistor 
)

(DEPRECATED) Save device profiles using the specified profile persistor.

Deprecated:
This function has moved to ProfileManager, accessible through getprofilemanager(). Time for removal is TBD.
Parameters
persistor(DeviceProfilePersistorBase): The device profile persistor.
Returns
None, raises an exception on errors

◆ setactiveprofile()

def ionicsdk.agent.Agent.setactiveprofile (   self,
  deviceid 
)

(DEPRECATED) Set the current device profile of the agent.

Deprecated:
This function has moved to ProfileManager, accessible through getprofilemanager(). Time for removal is TBD.
Parameters
deviceid(str): A string device id of a loaded profile to set as the active profile for the agent. If a DeviceProfile object is given instead it will use the deviceid parameter of the object as the string source.
Returns
None, raises an exception on errors

◆ setmetadata()

def ionicsdk.agent.Agent.setmetadata (   self,
  metadatadict 
)

Set metadata dictionary to be included with requests from this agent.

Parameters
metadatadict(MetadataDict, optional): The metadata properties to send along with the HTTP request.
Returns
None, raises an exception on errors

◆ updatekey()

def ionicsdk.agent.Agent.updatekey (   self,
  updateKeyData,
  metadata = None 
)

Updates the mutable portion of the attributes on a protection key at Ionic.com.

This method makes an HTTP call to Ionic.com to update protection keys.

Parameters
updateKeyData(UpdateKeyData): The key to be updated with mutable properties changed
metadata(MetadataDict, optional): The metadata properties to send along with the HTTP request.
Returns
A KeyData object containing the updated key.

Reimplemented from ionicsdk.services.AgentKeyServicesBase.

◆ updatekeys()

def ionicsdk.agent.Agent.updatekeys (   self,
  KeyDataArray,
  metadata = None 
)

Updates the mutable portion of the attributes on a list of protection keys at Ionic.com.

This method makes an HTTP call to Ionic.com to update protection keys.

Parameters
KeyDataArray(UpdateKeyDataList): The keys to be updated with mutable properties changed
metadata(MetadataDict, optional): The metadata properties to send along with the HTTP request.
Returns
A KeyDataList object containing the updated keys.

Reimplemented from ionicsdk.services.AgentKeyServicesBase.

◆ updateprofile()

def ionicsdk.agent.Agent.updateprofile (   self,
  deviceid = None,
  knsProviderUrl = None 
)

Finds the deviceId (or uses the active profile), gets the current KNS information for the profile keyspace, and then updates the profile (and active profile if needed).

The user is encouraged to save the profile afterward.

Parameters
deviceid(string): The device id of the profile to update, optional, uses active profile by default.
knsProviderUrl(unicode): The KNS provider url, optional, defaults to https://api.ionic.com
Returns
None, raises an exception on errors

The documentation for this class was generated from the following file: