net.sf.jmatchparser.util
Class BinaryExpression

java.lang.Object
  extended by 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


Copyright © 2011. All Rights Reserved.