obfuscator Documentation

Transcription

1 obfuscator Documentation Release Timothy McFadden July 17, 2015

2

3 Contents 1 Introduction 3 2 Install 5 3 Usage 7 4 Auto Generated API Documentation obfuscator.file obfuscator Indices and tables 13 Python Module Index 15 i

4 ii

5 obfuscator Documentation, Release Contents: Contents 1

6 obfuscator Documentation, Release Contents

7 CHAPTER 1 Introduction Obfuscator is a Python package used to obfuscate a set of data (e.g. bytes). It provides no encryption! It s strictly a security through obscurity tool, with limited usefulness. You have been warned! The project is hosted on GitHub at 3

8 obfuscator Documentation, Release Chapter 1. Introduction

9 CHAPTER 2 Install Download the latest release tarball and install with pip install <package>. You may also install directly from Pypi with pip install obfuscator. 5

10 obfuscator Documentation, Release Chapter 2. Install

11 CHAPTER 3 Usage See the unit tests for more in-depth examples. Here are the basics: import obfuscator original_bytes = map(ord, "testing") _key, obfuscated_bytes = obfuscator.obfuscate_xor(original_bytes, key=0x66) deobfuscated_bytes = obfuscator.deobfuscate_xor(key=0x66, data=obfuscated_bytes) assert original_bytes == deobfuscated_bytes If you use obfuscator.file to encode and decode strings, there is a miniature interface that you can use by importing the module directly: c:\code>python -m obfuscator.file Usage: python -m obfuscator.file encode-str <path-to-file> <key> "string to encode" python -m obfuscator.file decode-str <path-to-file> <key> c:\code>python -m obfuscator.file encode-str test.bin 10 "test\ning" [116, 101, 115, 116, 92, 110, 105, 110, 103] c:\code>python -m obfuscator.file decode-str test.bin 10 test\ning c:\code> 7

12 obfuscator Documentation, Release Chapter 3. Usage

13 CHAPTER 4 Auto Generated API Documentation Contents: 4.1 obfuscator.file This module contains a file-level interface for the XOR obfuscation methods. class obfuscator.file.obfuscatedfile(filename) Parameters filename (str) The path of the file you want to read/write. This class represents an obfuscated data file. You can use this to store some-what sensitive information inside a file. The documentation for some of the functions is purposely light. Example #1 - Storing a string: >>> from obfuscator.file import ObfuscatedFile >>> of = ObfuscatedFile('data.bin') >>> bytes = map(ord, "my string") >>> of.write(bytes) # data.bin is 32 bytes long 86 # The random key used for encoding; stored in the file >>> read_bytes = of.read() >>> read_bytes [109L, 121L, 32L, 115L, 116L, 114L, 105L, 110L, 103L] >>> ''.join(map(chr, read_bytes)) 'my string' Example #2 - Storing a string with known key: >>> from obfuscator.file import ObfuscatedFile >>> of = ObfuscatedFile('data.bin') >>> bytes = map(ord, "my string") >>> my_key = 0xCF >>> of.write(bytes, my_key) # data.bin is 32 bytes long 207 >>> read_bytes = of.read() # Notice how we didn't use a key >>> ''.join(map(chr, read_bytes)) ',8a253(/&' >>> # The string is wrong because the key is not stored in the file >>> read_bytes = of.read(key=my_key) >>> ''.join(map(chr, read_bytes)) 'my string' >>> 9

14 obfuscator Documentation, Release read(key=none) This function reads a file written by write, and returns the deobfuscated data. Parameters key (int) The key used during write(). NOTE: If you passed in a key during write(), you must use the same key here; the key will not be stored in the file. If you let the algorithm choose the key, it is stored in the file, and will be used during read(). write(data, key=none, minimum_length=32) Write the data to a file. Parameters data (iterable) The data you want to encode; the length of data must be less than 0xFF (header size limitation) key (int) The key used during encoding minimum_length (int) The minimum number of bytes to write. If the encoding operation produces fewer bytes that this, random bytes are appended to the end of the result so len(bytes) == minimum_length. 4.2 obfuscator This module contains a simple mechanism for obfuscating a set of data. Consider this security through obscurity. This module contains no encryption mechanisms! Example: >>> from obfuscator import obfuscate_xor, deobfuscate_xor >>> data = [1, 2, 3, 4] >>> key, odata = obfuscate_xor(data) >>> key, odata (162, [163, 160, 161, 166, 166, 154, 181, 60, 131, 24, 88, 35, 137, 240, 216, 161, 247, 218, 19, 116, >>> assert data == deobfuscate_xor(key, odata)[:len(data)] >>> >>> key, odata = obfuscate_xor(data, minimum_length=0) >>> assert data == deobfuscate_xor(key, odata) >>> obfuscator.deobfuscate(key, data, encoder=1) This function obfuscates the data using the default operation. obfuscator.deobfuscate_offset(key, data) This function deobfuscates the data using an offset operation. The formula used is: [x - key for x in data] Parameters key (int) The key used for the offset operation. data (iterable) The data you want to obfuscate obfuscator.deobfuscate_rot13(key, data) This function performs a ROT13 decode of the data. data needs to be an iterable that contains a representation of str types. This can be either a string of type str, or a list of bytes from something like ord. Parameters key (int) This value is ignored; it only exists to conform to the other methods. data (iterable) The data you want to deobfuscate 10 Chapter 4. Auto Generated API Documentation

15 obfuscator Documentation, Release obfuscator.deobfuscate_xor(key, data) This function deobfuscates the data using an byte-wise XOR operation. The formula used is: [x ^ key for x in data] Parameters key (int) The key used for the XOR operation. data (iterable) The data you want to obfuscate obfuscator.obfuscate(data, key=none, minimum_length=32, encoder=1) This function obfuscates the data using the default operation. obfuscator.obfuscate_offset(data, key=none, minimum_length=32) This function obfuscates the data using an offset operation. The formula used is: [x + key for x in data] Parameters data (iterable) The data you want to obfuscate key (int) The value used for the offset operation. By default, the value will be a random integer between 40 and 127. minimum_length (int) The minimum number of bytes to return. If the encoding operation produces fewer bytes that this, random bytes are appended to the end of the result so len(bytes) == minimum_length. obfuscator.obfuscate_rot13(data, key=none, minimum_length=32) This function performs a ROT13 encode on the data. data needs to be an iterable that contains a representation of str types. This can be either a string of type str, or a list of bytes from something like ord. Parameters data (iterable) The data you want to obfuscate key (int) This value is ignored; it only exists to conform to the other methods. minimum_length (int) The minimum number of bytes to return. If the encoding operation produces fewer bytes that this, random bytes are appended to the end of the result so len(bytes) == minimum_length. obfuscator.obfuscate_xor(data, key=none, minimum_length=32) This function obfuscates the data using an byte-wise XOR operation. The formula used is: [x ^ key for x in data] Parameters data (iterable) The data you want to obfuscate key (int) The key used for the XOR operation. By default, the key will be a random integer between 1 and 255. minimum_length (int) The minimum number of bytes to return. If the encoding operation produces fewer bytes that this, random bytes are appended to the end of the result so len(bytes) == minimum_length. obfuscator.rot13(data, minimum_length=32) This function performs a ROT13 encode/decode on the data. data needs to be an iterable that contains a representation of str types. This can be either a string of type str, or a list of bytes from something like ord. Parameters 4.2. obfuscator 11

16 obfuscator Documentation, Release data (iterable) The data you want to obfuscate minimum_length (int) The minimum number of bytes to return. If the encoding operation produces fewer bytes that this, random bytes are appended to the end of the result so len(bytes) == minimum_length. 12 Chapter 4. Auto Generated API Documentation

17 CHAPTER 5 Indices and tables genindex modindex search 13

18 obfuscator Documentation, Release Chapter 5. Indices and tables

19 Python Module Index o obfuscator, 10 obfuscator.file, 9 15

20 obfuscator Documentation, Release Python Module Index

21 Index D deobfuscate() (in module obfuscator), 10 deobfuscate_offset() (in module obfuscator), 10 deobfuscate_rot13() (in module obfuscator), 10 deobfuscate_xor() (in module obfuscator), 11 O obfuscate() (in module obfuscator), 11 obfuscate_offset() (in module obfuscator), 11 obfuscate_rot13() (in module obfuscator), 11 obfuscate_xor() (in module obfuscator), 11 ObfuscatedFile (class in obfuscator.file), 9 obfuscator (module), 10 obfuscator.file (module), 9 R read() (obfuscator.file.obfuscatedfile method), 9 rot13() (in module obfuscator), 11 W write() (obfuscator.file.obfuscatedfile method), 10 17