Client SDK Version 2.0.0
Ionic Security client SDK for Python users
Agent Overview

Introduction to Agent

Agent is the client-side library class for all Ionic.com API endpoint communication.


Using AgentKeyServices

Agent provides a default implementation of AgentKeyServices interface. It is possible for a user to override that interface and provide their own backend solution for key services (for example Offline Key Vault), that can be used by the ciphers for encryption and decryption.
Please see the AgentKeyServices Implementors Overview.


Initializing Agent

Before you can begin using an Agent object, it must first be initialized. The initialization process performs device profile loading and other non-trivial internal resource initialization to prepare it for secure communication with Ionic API servers.

Initializing an Agent object can be done a few different ways. If all configuration defaults are ok (which is typical) then you can simply create an Agent instance, Agent().

Simplest Example:

import ionicsdk
# create an agent and initialize it using all defaults
myAgent = ionicsdk.Agent()
# On error, the agent will throw an exception

If you need to provide some custom configuration, then you can create a configuration object and pass it to the Agent constructor.

Custom Configuration Example:

import ionicsdk
# Create an agent configuration object
myConfig = ionicsdk.AgentConfig('My Application Name')
myConfig.httptimeoutsecs = 20
myConfig.maxredirects = 2
# Initialize the agent from our config object
myAgent = ionicsdk.Agent(agentconfig=myConfig)


If you need to provide a custom device profile persistor to load device profiles using a custom implementation, then you can create it and pass it to the Agent constructor.

Custom Configuration with Custom Device Profile Persistor:

import ionicsdk
# Create an agent configuration object
myConfig = ionicsdk.AgentConfig('My Application Name')
myConfig.httptimeoutsecs = 20
myConfig.maxredirects = 2
# Use any non-default profile persistor.
profilePersistor = ionicsdk.DeviceProfilePersistorPlaintextFile("testfile.txt");
# Initialize the agent from the config object and persistor object.
# The persistor is used to automatically load device profiles.
myAgent = ionicsdk.Agent(agentconfig=myConfig, profilepersistor=profilePersistor)


KNS (Keyspace Name Service) features in SDK

The KNS features allow users to query information about a particular keyspace. Using the ionicsdk.agent.Agent.getkeyspace function users can get the tenant ID, the fully qualified domain name, the API URL and finally the enrollment URL. SDK clients (like the Machina CLI) can use this query during enrollment to get the enrollment URL. While enrollment will set up the initial API URL, a user can still use the KNS query to make sure the keyspace API URL hasn't moved. Finally, SDK includes a convenience function for updating a particular device profile, ionicsdk.agent.Agent.updateprofile.

import ionicsdk
# Create an agent and initialize it using all defaults
myAgent = ionicsdk.Agent()
# Update the active profile from the default Ionic KNS provider.
myAgent.updateprofile()
# ----- OR -----
# Retrieve the list of profiles.
proflist = myAgent.getallprofiles()
# Iterate over the list, and update each profile.
for profile in proflist:
myAgent.updateprofile(profile)
# ----- OR -----
# Retrieve the list of profiles
proflist = myAgent.getallprofiles()
# Iterate over the list, and update each profile, from a non-default KNS server
for profile in proflist:
myAgent.updateprofile(profile, "www.myknsserver.com")
# Finally, persist any changes
agent.saveprofiles();


Creating Keys

In order to protect sensitive data, keys must be requested from Agent using ionicsdk.agent.Agent.createkey or ionicsdk.agent.Agent.createkeys along with optional MetadataMap and AttributesMap objects to hold information about the application and data being secured.

Example of creating a single key:

import ionicsdk
# Create an agent and initialize it using all defaults
myAgent = ionicsdk.Agent()
# Set up our desired key attributes for the key
attributes = {"classification":("confidential",),"allowedGroups":("admins","mods")}
# Try to create the key.
# This will communicate with an Ionic server over the network.
createdKey = myAgent.createkey(attributes)

Example of creating multiple keys:

import ionicsdk
# Create an agent and initialize it using all defaults
myAgent = ionicsdk.Agent()
# Set up a key request object that will create five keys, each one having
# key attributes that indicate they will be protecting a social security number
attr = {"contains":("ssn",)}
createdKeys = myAgent.createkeys(5, attr)
# CreatedKeys is a list of 5 keys, or on error, createkeys will throw an exception