net.sf.jmatchparser.util
Class BinaryExpression

java.lang.Object
  net.sf.jmatchparser.util.BinaryExpression

public class BinaryExpression
extends Object

An expression that can be used to build or match binary byte arrays.

This is useful when binary data (like encryption keys) should be configurable in a text file, where the user can decide which format (hex, base64, etc.) he wants to use to provide the data.

Therefore, the user can give a list of transformations (separated by colons), followed by data to be transformed. Each transformation is applied on the result of the previous transformation. Therefore, hex:base64:NzQ2NTczNzQ= will result in test.

An empty transformation name will stop parsing transformations; therefore, to match the literal (UTF-8) bytes C:\>, the expression :C:\> can be used. If no encoding is given, everything is encoded as UTF-8. An explicit encoding can be given by using the encode- <encoding>: transformation.

Optionally, a secondary expression can be parsed at the same time, for example an initialization vector for an encryption key or a mask for matching data. In case of a mask, MaskedBinaryExpression might have been the better choice.

The following tranformations are supported:

hex

decode hexadecimal, like hex:444a32 -> DJ2

base64

decode base64, like base64:SGVsbG8= -> Hello

sha1

Encode SHA1, like sha1:test -> hex:a94a8fe5ccb19ba61c4c0873d391e987982fbbd3

md5

Encode MD5, like md5:test -> hex:098f6bcd4621d373cade4e832627b4f6

hash-algorithm

Encode any hash algorithm; hash-MD5 is equivalent to md5, hash-SHA-1 is equivalent to sha1

split

Split the expression into multiple expressions, delimited by a custom character directly following the colon after split, like split:#Area#hex:35#1 -> Area51

unescape

Parse Java escapes, like unescape:\r\n -> hex:0d0a, or unescape:Some€for\44 -> Some€for$

encode-charset

Encode in a given charset, like encode-ISO-8859-15:€ -> hex:a4, or encode-UTF-8:€ -> hex:E282AC

map

Select a given range of characters (or more than one) out of another expression, like map1-4+5-9o+9+3+3:987654321 -> 9876531177. The result of a map expression may be up to 4KB long.

secondaryName

Similar to map, but store the result as the secondary value. When in random mode, also supports expressions like 4r for 4 random characters; when not in random mode, it can use 3-5?, meaning that characters 3 to 5 are copied to the secondary value, but marked as optional.

Constructor Summary

BinaryExpression(String expression, String secondaryName, boolean secondaryRandom)
Create a new binary expression with optional secondary expressions

Method Summary

boolean[]	getMarkedSecondaryBytes() Return the bytes marked (as optional or random) in the secondary value, if any.
byte[]	getRandomSecondaryValue(Random randomSource) Compute a new random secondary value.
byte[]	getSecondaryValue() Return the secondary value, if any.
byte[]	getValue() Return the value of the parsed expression.
static byte[]	parseBinaryExpression(String expression) Parse a binary expression with no secondary expression.
static String	unescape(String string, String literalChars) Unescape Java escape sequences like \n or octal or unicode escapes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BinaryExpression

public BinaryExpression(String expression,
                        String secondaryName,
                        boolean secondaryRandom)
                 throws IOException

Create a new binary expression with optional secondary expressions

Parameters:

expression - Expression to parse

secondaryName - Name used in the expression to denote secondary expression (like mask or iv)

secondaryRandom - Whether the secondary expression may contain random bytes (like an iv); if not, the marked bytes are optional instead of random

Throws:

IOException

Method Detail

parseBinaryExpression

public static byte[] parseBinaryExpression(String expression)
                                    throws IOException

Parse a binary expression with no secondary expression.

Throws:

IOException

unescape

public static String unescape(String string,
                              String literalChars)
                       throws IOException

Unescape Java escape sequences like \n or octal or unicode escapes.

Parameters:

string - The string to unescape

literalChars - List of characters (like quotation marks) that should return themselves instead of producing an error. A backslash will always return itself regardless whether it is in this list or not.

Throws:

IOException

getValue

public byte[] getValue()

Return the value of the parsed expression.

getSecondaryValue

public byte[] getSecondaryValue()

Return the secondary value, if any.

getMarkedSecondaryBytes

public boolean[] getMarkedSecondaryBytes()

Return the bytes marked (as optional or random) in the secondary value, if any.

getRandomSecondaryValue

public byte[] getRandomSecondaryValue(Random randomSource)

Compute a new random secondary value. This works only if the secondary value was parsed in random mode.

Parameters:

randomSource - source for the randomness