cascada.abstractproperty.property module

Provide a base class for properties like Difference, LinearMask or Value.

`Property`	Represent bit-vector properties.
`PropConcat`	Subclass of `Concat` that propagates properties naturally.
`PropExtract`	Subclass of `Extract` that propagates properties naturally.
`make_partial_propextract`	Return a `PartialOperation` of `PropExtract` that propagates properties naturally.

class cascada.abstractproperty.property.Property(value)[source]

Bases: object

Represent bit-vector properties.

A (bit-vector) property pair, or simply a property, over a function \(f\) is a pair of bit-vectors \((\alpha, \beta)\) with an associated propagation probability \(PP_f(\alpha, \beta)\). In this case, we also say that the input property \(\alpha\) propagates to the output property \(\beta\) with probability \(PP_f(\alpha, \beta)\).

Each instance of this class represents an input or output property; the underlying bit-vector value of the input or output property is stored in the attribute val, but the associated function \(f\) is not stored within the Property object.

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

This class is not meant to be instantiated but to provide a base class to define bit-vector properties such as Difference, LinearMask or Value.

val: a Term representing the underlying value of the property.

xreplace(rule)[source]

Replace occurrences of properties 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 Property objects are allowed in rule.

vrepr()[source]

Return an executable string representation.

This method returns a string so that the relation eval(self.vrepr()) == self holds.

classmethod propagate(op, input_prop)[source]

Propagate the given input property through the given operation.

Given a function \(y = f(x)\), an input property \(p_x\) propagates (over \(f\)) to an output property \(p_y\) if the propagation probability \(PP_f(\alpha, \beta)\) is not zero.

Note that if \(f\) has \(t\) operands, the input property is actually a list of \(t\) properties, that is, \(p_x = (p_{x_0}, p_{x_1}, \dots, p_{x_{t-1}})\), and similar for \(p_y\).

For some functions, any input property propagates to a unique output property with probability 1, and the output property can be easily computed from the input property.

Examples of probability-one propagations are the following:

For the Value property type, for any operation \(f\) and any input property \(p_x\), the output property \(p_y\) is uniquely determined and its bit-vector value is f(p_x.val).
For the Difference property type with difference operation \(-\) (e.g., XOR), for any linear (over \(-\)) operation \(f\) and any input property \(p_x\), the output property \(p_y\) is uniquely determined and its bit-vector value is f(p_x.val).
For the LinearMask property, for any XOR-linear operation \(f\) and any input property \(p_x\), the output property \(p_y\) is uniquely determined and its bit-vector value satisfies p_x.val == M(p_y.val), where \(M\) is the transpose of the binary matrix representing \(f\).

If for the given Operation op any input property propagates to a unique output property with probability 1 and the output property can be easily computed from the input property, this method returns the corresponding output property (for the given input property input_prop) as a Property object. Otherwise, this method returns the abstractproperty.opmodel.OpModel of the operation op with the given input property input_prop.

Note

Operations op with scalar operands are not supported, but these operands can be removed with make_partial_operation and partial operations are supported by this method.

Parameters

op – the bit-vector operator \(f\) as an Operation subclass
input_prop – a list containing the input Property for each operand of op (or simply the Property object if there is only one operand)

class cascada.abstractproperty.property.PropConcat(**kwargs)[source]

Bases: cascada.bitvector.operation.Concat

Subclass of Concat that propagates properties naturally.

The only difference between Concat and PropConcat is that the latter one propagates (see Property.propagate) an input Property list p0, p1 as Property(Concat(p0.val, p1.val)).

class cascada.abstractproperty.property.PropExtract(**kwargs)[source]

Bases: cascada.bitvector.operation.Extract

Subclass of Extract that propagates properties naturally.

The only difference between Extract and PropExtract is that the latter one (with fixed operands) propagates (see Property.propagate) an input Property p as Property(Extract_{·, i, j}(p0.val)), where i, j are the fixed operands.

cascada.abstractproperty.property.make_partial_propextract(i, j)[source]: Return a PartialOperation of PropExtract that propagates properties naturally.