Developer Interface

This part of the documentation covers all the interfaces exposed by the Padding Oracle Exploit API.

Main Interface

Tool authors should subclass the PaddingOracle class and implement oracle(). A typical example may look like:

from paddingoracle import PaddingOracle, BadPaddingException

class PadBuster(PaddingOracle):
    def oracle(self, data):

        #
        # code to determine if a padding oracle is revealed
        # if a padding oracle is revealed, raise a BadPaddingException
        #

        raise BadPaddingException

To exploit the padding oracle vulnerability, simply:

padbuster = PadBuster()
decrypted = padbuster.decrypt(encrypted_data)

print decrypted

That’s all! The hard work of actually carrying out the attack is handled in the PaddingOracle.bust() method (not documented), which in turns calls the oracle() method implemented by your code.

class paddingoracle.PaddingOracle(**kwargs)

Implementations should subclass this object and implement the oracle() method.

Parameters:max_retries (int) – Number of attempts per byte to reveal a padding oracle, default is 3. If an oracle does not reveal itself within max_retries, a RuntimeError is raised.

decrypt(ciphertext, block_size=8, iv=None, **kwargs)

Decrypts ciphertext by exploiting a Padding Oracle.

Parameters:

• ciphertext – Encrypted data.
• block_size (int) – Cipher block size (in bytes).
• iv – The initialization vector (iv), usually the first block_size bytes from the ciphertext. If no iv is given or iv is None, the first block_size bytes will be used.

Returns:

Decrypted data.

encrypt(plaintext, block_size=8, iv=None, **kwargs)

Encrypts plaintext by exploiting a Padding Oracle.

Parameters:

• plaintext – Plaintext data to encrypt.
• block_size (int) – Cipher block size (in bytes).
• iv – The initialization vector (iv), usually the first block_size bytes from the ciphertext. If no iv is given or iv is None, the first block_size bytes will be null’s.

Returns:

Encrypted data.

oracle(data, **kwargs)

Feeds data to a decryption function that reveals a Padding Oracle. If a Padding Oracle was revealed, this method should raise a BadPaddingException, otherwise this method should just return.

A history of all responses should be stored in history, regardless of whether they revealed a Padding Oracle or not. Responses from history are fed to analyze() to help identify padding oracles.

Parameters:data (bytearray) – A bytearray of (fuzzed) encrypted bytes. Raises :BadPaddingException if decryption reveals an oracle.

analyze(**kwargs)

This method analyzes return oracle() values stored in history and returns the most likely candidate(s) that reveals a padding oracle.

Exceptions

exception paddingoracle.BadPaddingException

Raised when a blackbox decryptor reveals a padding oracle.

This Exception type should be raised in PaddingOracle.oracle().