Machina Client SDK Version 2.1.2
Ionic Security Machina Client SDK for Python users
Welcome to the Ionic Security Machina Client SDK for Python!

Introduction to the SDK

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

Version

The Machina Client SDK version is 2.1.2

Overview

  • Agent Overview. Supports secure communication with Ionic API servers for key creation, retrieval, etc.
  • FileCipher Overview. Supports protection of files of all types.
  • ChunkCrypto Overview. Supports protection of small-medium sized text strings and binary arrays.
  • Crypto Overview. Supports standard AES 256 GCM / CTR, etc.
  • KeyVault Overview. Supports local, temporary, secure storage of data protection keys.
  • Logging. Supports flexible and extensible logging for the SDK and any consuming application.

Module List

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

The same can be seen broken down by SDK module:

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.IonicError:
Any Ionic error code can be translated into a human-readable string via ionicsdk.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.

Logging

The Python SDK supports highly configurable logging that can be very useful when troubleshooting problems, auditing the activities of an application, etc. See ionicsdk.log for extensive documentation on this module.

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().

Proxy settings

Python uses the native C library which by default uses the operating system's native interface. The Python interpreter will normally use OS proxy settings as well. However on Windows and OSX, if Unix style (HTTP_PROXY environment variable) proxy settings are present, the python interpreter may use those instead while the Ionic Python SDK will use the OS settings. If an issue with proxies develops, there may be unique or leftover proxy settings for Python that you can try removing or replicating to the operating system settings.