arxpy.differential.difference module

Manipulate differences.

class arxpy.differential.difference.Difference(value)

Bases: object

Represent differences.

The difference between two Term \(x\) and \(y\) is defined as \(\alpha = y - x\), where the difference operation \(-\) is a bit-vector Operation. In other words, the pair \((x, x + \alpha)\) has difference \(\alpha\), where \(+\) is the inverse of the difference operation.

The most common difference used in differential cryptanalysis is the XOR difference XorDiff (where the difference operation is BvXor). Other examples are the additive difference (where the difference operation is BvSub) or the rotational-XOR difference RXDiff.

Note that arithmetic with differences is not supported. For example, two Difference objects d1 and d2 cannot be XORed, i.e., d1 ^ d2. This can be done instead by performing the arithmetic with the difference values and converting the resulting Term to a difference, that is, Difference(d1.val ^ d2.val)

This class is not meant to be instantiated but to provide a base class for the different types of differences.

val

a Term representing the value of the difference.

diff_op

the difference Operation.

inv_diff_op

the inverse of the difference operation.

xreplace(rule)

Replace occurrences of differences within the expression.

The argument rule is a dict-like object representing the replacement rule.

This method is similar to SymPy xreplace but with the restriction that only differences objects are allowed in rule.

vrepr()

Return a verbose string representation.

classmethod from_pair(x, y)

Return the Difference \(\alpha = y - x\) given two Term.

get_pair_element(x)

Return the Term \(y\) such that \(y = \alpha + x\).

classmethod derivative(op, input_diff)

Return the derivative of op at the point input_diff.

The derivative of an Operation \(f\) at the point \(\alpha\) (also called the input difference) is defined as \(f_{\alpha} (x) = f(x + \alpha) - f(x)\). Note that \(f_{\alpha} (x)\) is the difference of \((f(x), f(x + \alpha))\).

If \(f\) has multiple operands, \(\alpha\) is a list containing the Difference of each operand and the computation \(x + \alpha\) is defined component-wise, that is, \(x = (x_1, \dots, x_n)\), \(\alpha = (\alpha_1, \dots, \alpha_n)\), and \(x + \alpha = (x_1 + \alpha_1, \dots, x_n + \alpha_n)\).

For some operations, there is a unique output difference \(\beta\) for every input difference \(\alpha\), that is, \(f_{\alpha}(x) = \beta\) is a constant function. In this case, this method returns the Difference \(\beta\). Otherwise, it returns a Derivative object representing \(f_{\alpha}\).

Operations with scalar operands are not supported, but these operands can be removed with make_partial_operation and the derivative of the resulting operator can then be computed.

Parameters

• op – a bit-vector operator

• input_diff – a list containing the difference of each operand

class arxpy.differential.difference.XorDiff(value)

Bases: arxpy.differential.difference.Difference

Represent XOR differences.

The XOR difference of two Term is given by the XOR of the terms. In other words, the difference operation of XorDiff is the BvXor (see Difference).

>>> from arxpy.bitvector.core import Constant, Variable
>>> from arxpy.differential.difference import XorDiff
>>> x, y = Constant(0b000, 3), Constant(0b000, 3)
>>> alpha = XorDiff.from_pair(x, y)
>>> alpha
XorDiff(0b000)
>>> alpha.get_pair_element(x)
0b000
>>> x, y = Constant(0b010, 3), Constant(0b101, 3)
>>> alpha = XorDiff.from_pair(x, y)
>>> alpha
XorDiff(0b111)
>>> alpha.get_pair_element(x)
0b101
>>> k = Variable("k", 8)
>>> alpha = XorDiff.from_pair(k, k)
>>> alpha
XorDiff(0x00)
>>> alpha.get_pair_element(k)
k

diff_op

alias of arxpy.bitvector.operation.BvXor

inv_diff_op

alias of arxpy.bitvector.operation.BvXor

classmethod derivative(op, input_diff)

Return the derivative of op at the point input_diff.

See Difference.derivative for more information.

>>> from arxpy.bitvector.core import Variable, Constant
>>> from arxpy.bitvector.operation import BvAdd, BvXor, RotateLeft, BvSub
>>> from arxpy.bitvector.extraop import make_partial_operation
>>> from arxpy.differential.difference import XorDiff
>>> d1, d2 = XorDiff(Variable("d1", 8)), XorDiff(Variable("d2", 8))
>>> XorDiff.derivative(BvXor, [d1, d2])
XorDiff(d1 ^ d2)
>>> Xor1 = make_partial_operation(BvXor, tuple([None, Constant(1, 8)]))
>>> XorDiff.derivative(Xor1, d1)
XorDiff(d1)
>>> Rotate1 = make_partial_operation(RotateLeft, tuple([None, 1]))
>>> XorDiff.derivative(Rotate1, d1)
XorDiff(d1 <<< 1)
>>> XorDiff.derivative(BvAdd, [d1, d2])
XDA(XorDiff(d1), XorDiff(d2))
>>> XorDiff.derivative(BvSub, [d1, d2])
XDS(XorDiff(d1), XorDiff(d2))
>>> CteAdd1 = make_partial_operation(BvAdd, tuple([None, Constant(1, 8)]))
>>> XorDiff.derivative(CteAdd1, d1)
XDCA_0x01(XorDiff(d1))

class arxpy.differential.difference.RXOp

Bases: arxpy.bitvector.operation.Operation

The difference operation of RXDiff.

classmethod condition(x, y)

Check if the operands verify the restrictions of the operator.

classmethod output_width(x, y)

Return the bit-width of the resulting bit-vector.

classmethod eval(x, y)

Evaluate the operator with given operands.

This is an internal method. To evaluate a bit-vector operation, use the operator ().

class arxpy.differential.difference.RXInvOp

Bases: arxpy.bitvector.operation.Operation

The inverse of the difference operation of RXDiff.

classmethod condition(x, d)

Check if the operands verify the restrictions of the operator.

classmethod output_width(x, d)

Return the bit-width of the resulting bit-vector.

classmethod eval(x, d)

Evaluate the operator with given operands.

This is an internal method. To evaluate a bit-vector operation, use the operator ().

class arxpy.differential.difference.RXDiff(value)

Bases: arxpy.differential.difference.Difference

Represent rotational-XOR (RX) differences.

The pair (x, (x <<< 1) ^ d) has RX difference d. In other words, the RX difference of two Terms x and y is defined as (x <<< 1) ^ y.

See Difference for more information.

>>> from arxpy.bitvector.core import Constant, Variable
>>> from arxpy.differential.difference import RXDiff
>>> x, y = Constant(0b000, 3), Constant(0b000, 3)
>>> alpha = RXDiff.from_pair(x, y)
>>> alpha
RXDiff(0b000)
>>> alpha.get_pair_element(x)
0b000
>>> x, y = Constant(0b000, 3), Constant(0b001, 3)
>>> alpha = RXDiff.from_pair(x, y)
>>> alpha
RXDiff(0b001)
>>> alpha.get_pair_element(x)
0b001
>>> k = Variable("k", 8)
>>> alpha = RXDiff.from_pair(k, k)
>>> alpha
RXDiff(k ^ (k <<< 1))
>>> alpha.get_pair_element(k)
k

diff_op

alias of RXOp

inv_diff_op

alias of RXInvOp

classmethod derivative(op, input_diff)

Return the derivative of op at the point input_diff.

See Difference.derivative for more information.

>>> from arxpy.bitvector.core import Variable, Constant
>>> from arxpy.bitvector.operation import BvAdd, BvXor, RotateLeft
>>> from arxpy.bitvector.extraop import make_partial_operation
>>> from arxpy.differential.difference import RXDiff
>>> d1, d2 = RXDiff(Variable("d1", 8)), RXDiff(Variable("d2", 8))
>>> RXDiff.derivative(BvXor, [d1, d2])
RXDiff(d1 ^ d2)
>>> Xor1 = make_partial_operation(BvXor, tuple([None, Constant(1, 8)]))
>>> RXDiff.derivative(Xor1, d1)
RXDiff(0x03 ^ d1)
>>> Rotate1 = make_partial_operation(RotateLeft, tuple([None, 1]))
>>> RXDiff.derivative(Rotate1, d1)
RXDiff(d1 <<< 1)
>>> RXDiff.derivative(BvAdd, [d1, d2])
RXDA(RXDiff(d1), RXDiff(d2))