Agent SDK
Welcome to the Ionic Security Client SDK for Python!

Table of Contents

Introduction to the SDK

The Client SDK for Python is a client-side library provided by Ionic Security for the purpose of protecting data anywhere and everywhere.


The Client SDK version is 1.6.0.


A convenient breakdown of all classes, functions, types, enums, etc can be seen here.

The same can be seen broken down by SDK module:

Using ISAgentKeyServices

ISAgent provides a default implementation of ISAgentKeyServices 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.

Error Handling

Error handling in the Python SDK is done with error codes or exceptions. For functions that return object pointers instead of an integer error code, None is returned in the case of error. In all cases of error, the exact nature of the error is output through the SDK logger. Logging can be turned on via ionic_log_setup_simple() or a variant (see Logging).

Error codes are in ionicsdk.errors:
Any Ionic error code can be translated into a human-readable string via IonicError.toString().

Thread Safety

All objects in the Python SDK are not thread-safe. This means that any function which operates on an object pointer (e.g. ionicsdk.agent, ionicsdk.filecipher) must not be used with the same object in more than one thread. This means that agent objects, cipher objects, etc. must not be shared across threads. The functions themselves are thread-safe, but the objects on which they operate are not. Because of the nature of Python, multi-process is usually a much better approach than multi-thread - were possible. However, since most of the Ionic functionality happens in native code and is often waiting on server responses anyway, multi-thread should be possible where care is taken.

For example, calling ionicsdk.filecipher.FileCipherAuto.encrypt(myCipher1) on one thread while calling ionicsdk.filecipher.FileCipherAuto.encrypt(myCipher1) on another thread is not acceptable and will result in undefined behavior. However, calling ionicsdk.filecipher.FileCipherAuto.encrypt(myCipher1) on one thread while calling ionicsdk.filecipher.FileCipherAuto.encrypt(myCipher2) on another thread is acceptable because although the same function is being called, each call is operating on a different cipher object.

Functions that do not operate on object pointers are thread-safe. For example, ionicsdk.filecipher.FileCrypto.getinfo(), ionicsdk.log.setup_simple(), and ionicsdk.filecipher.FileCipherFamily.tostring() can be called from any number of threads at any time.

Strings, Encodings, etc.

Without exception, all input and output strings provided to and from the SDK must use the 'unicode' string class and and not 'string'. Doing so enables universal language interoperability with very little effort and with a very widely established Unicode format. Underneath, these 'unicode' type strings are generally passed around on the native side as UTF-8. However, putting UTF-8 strings in the vanilla 'string' instances generally doesn't work as well in Python. Python will often attempt to convert these strings up to the 'unicode' type without the user necessarily intending the conversion. Since Python doesn't know your 'string' instances contain UTF-8, this often results in corruption of the data. Always use 'unicode', never 'string'.

It should be noted that this rule is especially important when encrypting strings with any of the supported ciphers. This is because the resulting ciphertext may be decrypted in a completely different environment (OS and/or programming language) in which it is assumed that the decrypted plaintext is UTF-8 encoded. If the decrypted plaintext is not UTF-8 encoded, then problems may arise. For example, if decrypting to a string using the .NET SDK, the decrypted plaintext string must be transcoded to UTF-16 since that is the universal string encoding for .NET. The transcoding operation will fail if the original plaintext string was not 'unicode' on the Python side.


The Python SDK supports highly configurable logging that can be very useful when troubleshooting problems, auditing the activities of an application, etc.

The simplest way to enable logging is to call ionicsdk.log.setup_simple(). For more fine grained control, which can enable multiple log writers of various types, various filter levels, etc., you can configure the logger from a JSON configuration file (ionicsdk.log.setup_from_config_file()) or string (ionicsdk.log.setup_from_config_json()).

Once logging is configured, SDK logs will begin to be emitted. The application developer may also write messages through the same logger via call to ionicsdk.log.log().