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

Introduction to FileCipher

The FileCipher module supports encryption and decryption of all file types.


Thread Safety

FileCipher is not thread-safe. All classes in the FileCipher module are not thread-safe and should not be used as a shared resource between concurrent threads. In order to use objects in a multi-threaded environment, it is recommended to create one object per thread.


File Cipher Classes


File Cipher Families and Versions

Each file cipher class (see File Cipher Classes) supports a single format "family" and one or more format versions. The term family is used because some ciphers support a collection of related formats.

For example, ionicsdk.filecipher.FileCipherOpenXml supports Microsoft Office Open XML formatted files, including Word (.docx), Excel (.xlsx), etc. This family is known as ionicsdk.filecipher.FileCipherFamily.FAMILY_OPENXML. ionicsdk.filecipher.FileCipherOpenXml supports various Ionic format versions (e.g. "1.1", "1.0"), and more versions may be added over time to fix security issues, reduce file size, or otherwise improve upon the older formats.


Cover Pages and Access Denied Pages

The advantage of the various ciphers specific to a certain file type is that they wrap the encrypted content inside a cover page. For example, a PDF file encrypted with the PDF cipher generates a valid PDF file, which can be loaded into any PDF reader. Of course, the viewed file will just display a notice of the encrypted status. The file must be decrypted to view its actual content. Similarly, the decrypt functions will return a valid "Access Denied" page of the cipher type, if desired. These pages are builtin to the SDK, but can be replaced with a local version using a custom implementation of ionicsdk.coverpage.CoverPageService.


The Automatic File Cipher

ionicsdk.filecipher.FileCipherAuto is a special cipher in the sense that it does not represent a format of its own, but instead it automatically chooses the correct file cipher to use (e.g. ionicsdk.filecipher.FileCipherOpenXml, ionicsdk.filecipher.FileCipherPdf) based on the contents of the file being encrypted / decrypted. Using this cipher is recommended in most cases since it simplifies the code of the consuming application. An example can be seen here: Example Usage - Simple.

Important Limitations

The automatic file cipher cannot and does not detect CSV or CMS file types automatically for encryption. Only decryption of these file types are supported automatically.

CSV files do not follow any standard or documented format, can contain any type of delimiter, may not contain any delimiters at all, etc. For this reason, the automatic file cipher will encrypt CSV files using the generic file cipher (ionicsdk.filecipher.FileCipherGeneric) as opposed to the specialized CSV file cipher (ionicsdk.filecipher.FileCipherCsv). When the CSV file cipher is desired, it must be used directly instead of relying on the automatic cipher.

Similarly, the CMS cipher will encrypt any input as the payload (typically a MIME encoded file attachment). Only the resultant encrypted CMS message follows a documented format. Therefore, when the CMS file cipher is desired for encryption, it must be used directly instead of relying on the automatic cipher.


Example Usage - Simple

import ionicsdk
# Create an agent and initialize it using all defaults.
myAgent = ionicsdk.Agent()
cipher = ionicsdk.FileCipherAuto(myAgent)
# Encrypt a test file and then decrypt it.
cipher.encrypt("MyTestFile.docx", "MyEncryptedFile.docx")
cipher.decrypt("MyEncryptedFile.docx", "MyRecoveredFile.docx")
# Encrypt a file in place.
cipher.encryptinplace("MyTestFile.docx")


Example Usage - Advanced

import ionicsdk
# Create an agent and initialize it using all defaults.
myAgent = ionicsdk.Agent()
cipher = ionicsdk.FileCipherAuto(myAgent)
# Use a FileCipherEncryptAttributes object to provide key attributes that
# describe some aspects of the document being encrypted.
attributes = { "classifications": ["c1", "c2"], "color": ["green"] }
mutableAttributes = {'Date':['Jan 1', '1970'], 'Salary':['Hamburgers',]}
metadata = { "test-meta-key": "test-meta-value" }
# Perform encryption.
encryptattrs = ionicsdk.FileCipherEncryptAttributes(attributes, metadata, None, mutableAttributes)
# Encrypt a test file.
cipher.encrypt2("MyTestFile.docx", "MyEncryptedFile.docx", encryptattrs)
# Decrypt the file that we just encrypted.
decryptattrs = ionicsdk.FileCipherDecryptAttributes(metadata)
cipher.decrypt2("MyEncryptedFile.docx", "MyRecoveredFile.docx", decryptattrs)