Merge branch 'release/2.0'

Keysight · Nov 27, 2020 · bdb3fc5 · bdb3fc5
2 parents f6e8fc6 + f7b7569
commit bdb3fc5
Show file tree

Hide file tree

Showing 27 changed files with 1,682 additions and 122 deletions.
diff --git a/README.md b/README.md
@@ -25,6 +25,76 @@ When not supplied at creation time, the following parameters are defined based o
         Since this is dynamically decided based on the values of the first trace, 
         it can be beneficial to force floats by calling Trace.forceFloatCoding() for the first trace. 
 
+### Using the TRS V2 additions
+As of release 2.0, two additional provisions were added to the .trs format: Trace Set Parameters and Trace Parameters. Note that TRS V2 is backwards compatible with TRS V1. However, as can be expected, the additional information will not be available when using a pre-V2 reader.
+#### Trace Set Parameters
+Trace Set Parameters are user-defined key value pairs that can be used to save global information about the trace set. The following types of data can be used (also found in com.riscure.trs.parameter.ParameterTypes):
+
+     BYTE: 1 byte integer
+     SHORT: 2 byte integer
+     INT: 4 byte integer
+     FLOAT: 4 byte floating point
+     LONG: 8 byte integer
+     DOUBLE: 8 byte floating point
+     STRING: UTF-8 encoded string value
+Each type also supports array creation. Please note that there is no provision for arrays of length 1. An array of length 1 will always be saved and loaded as a single value.
+##### Using Trace Set Parameters
+Global parameters can be added by creating a `TraceSetParameters` object when creating a trace set. The following java code shows an example:
+```java
+TRSMetaData metaData = new TRSMetaData();
+metaData.put(TRSTag.TRS_VERSION, 2);
+TraceSetParameters parameters = new TraceSetParameters();
+parameters.put("BYTE", (byte)1);
+parameters.put("SHORT", (short)2);
+parameters.put("INT", 3);
+parameters.put("FLOAT", (float)4);
+parameters.put("LONG", (long)5);
+parameters.put("DOUBLE", (double)6);
+parameters.put("STRING", String.format("%3d", 7));
+parameters.put("BYTEARRAY", new byte[]{(byte) 8, (byte) 9, (byte) 0});
+parameters.put("SHORTARRAY", new short[]{(short) 1, (short) 2, (short) 3});
+parameters.put("INTARRAY", new int[]{4, 5, 6});
+parameters.put("FLOATARRAY", new float[]{(float) 7, (float) 8, (float) 9});
+parameters.put("LONGARRAY", new long[]{0, 1, 2});
+parameters.put("DOUBLEARRAY", new double[]{3, 4, 5});
+metaData.put(TRSTag.TRACE_SET_PARAMETERS, parameters);
+TraceSet ts = TraceSet.create("PATH_TO_NEW_TRS_FILE", metaData);
+//Add traces here
+ts.close();
+```
+
+#### Trace Parameters
+TraceParameters behave very similar to Trace Set Parameters from a user perspective. They are values that can be added to _every_ trace, describing specific values that can vary between traces. The data types that can be used are the same as for Trace Set Parameters. However, there are several details that are different:
+
+    1. The length of the added information *must* be the same for every trace. This means that the first trace added to the trace set dictates the length of both arrays _and_ strings. If a longer string is added later, it will be truncated.
+    2. The length of every parameter is saved in the header at creation time, in a structure called `TraceParameterDefinitions`. This structure is used when reading out the traces to determine the structure of the included data. This information is _not_ added to the individual traces themselves.
+    3. Going forward, there will be pre-defined tags used to mark important information. At time of writing, the following tags are known:
+        INPUT: the byte array used as input to a cryptographic algorithm
+        OUTPUT: the byte array returned by a cryptographic algorithm
+        KEY: the byte array used as key for a cryptographic operation
+        SAMPLES: An alternative for saving the samples of a trace. This may in the future replace the predefined trace structure of title-data-samples.
+        TITLE: An alternative for saving the title of a trace. This may in the future replace the predefined trace structure of title-data-samples.
+##### Using Trace Parameters
+Local parameters can be added by creating a `TraceParameters` object when creating a trace. The following java code shows an example:
+```java
+TraceParameters parameters = new TraceParameters();
+parameters.put("BYTE", (byte)1);
+parameters.put("SHORT", (short)2);
+parameters.put("INT", 3);
+parameters.put("FLOAT", 4.0f);
+parameters.put("LONG", 5L);
+parameters.put("DOUBLE", 6.0);
+parameters.put("STRING", "A string");
+parameters.put("BYTEARRAY", new byte[]{(byte) 1, (byte) 2, (byte) 3});
+parameters.put("SHORTARRAY", new short[]{(short) 4, (short) 5, (short) 6});
+parameters.put("INTARRAY", new int[]{7, 8, 9});
+parameters.put("FLOATARRAY", new float[]{0.0f, 1.0f, 2.0f});
+parameters.put("LONGARRAY", new long[]{3L, 4L, 5L});
+parameters.put("DOUBLEARRAY", new double[]{6.0, 7.0, 8.0});
+Trace.create("trace title", new float[0], parameters);
+```
+Note that the previously mentioned `TraceParameterDefinitions` are created automatically when adding the first trace.
+
 ### Reading `.trs` files
 ```java
 import com.riscure.trs.Trace;
@@ -72,6 +142,7 @@ traceSet.add(com.riscure.trs.Trace("Trace 0        ", [0x0, 0x0f, 0xA, 0x3C], [0
 traceSet.close();
 ```
 
+
 ## Documentation
 TODO
 

diff --git a/pom.xml b/pom.xml
@@ -6,7 +6,7 @@
 
     <groupId>com.riscure</groupId>
     <artifactId>trsfile</artifactId>
-    <version>1.1-SNAPSHOT</version>
+    <version>2.0</version>
 
     <properties>
         <maven.compiler.source>1.8</maven.compiler.source>
@@ -43,6 +43,19 @@
                 </executions>
             </plugin>
 
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-resources-plugin</artifactId>
+                <configuration>
+                    <resources>
+                        <resource>
+                            <directory>src/main/resources</directory>
+                            <filtering>true</filtering>
+                        </resource>
+                    </resources>
+                </configuration>
+            </plugin>
+
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-clean-plugin</artifactId>
@@ -71,6 +84,11 @@
                     <artifactId>maven-source-plugin</artifactId>
                     <version>3.2.0</version>
                 </plugin>
+                <plugin>
+                    <groupId>org.apache.maven.plugins</groupId>
+                    <artifactId>maven-resources-plugin</artifactId>
+                    <version>3.1.0</version>
+                </plugin>
                 <plugin>
                     <groupId>org.apache.maven.plugins</groupId>
                     <artifactId>maven-clean-plugin</artifactId>
@@ -84,7 +102,7 @@
         <dependency>
             <groupId>junit</groupId>
             <artifactId>junit</artifactId>
-            <version>4.12</version>
+            <version>4.13.1</version>
             <scope>test</scope>
         </dependency>
     </dependencies>

diff --git a/src/main/java/com/riscure/trs/HexUtils.java b/src/main/java/com/riscure/trs/HexUtils.java
@@ -0,0 +1,17 @@
+package com.riscure.trs;
+
+import java.nio.charset.StandardCharsets;
+
+public class HexUtils {
+    private static final byte[] HEX_ARRAY = "0123456789ABCDEF".getBytes(StandardCharsets.UTF_8);
+
+    public static String toHexString(byte[] bytes) {
+        byte[] hexChars = new byte[bytes.length * 2];
+        for (int j = 0; j < bytes.length; j++) {
+            int v = bytes[j] & 0xFF;
+            hexChars[j * 2] = HEX_ARRAY[v >>> 4];
+            hexChars[j * 2 + 1] = HEX_ARRAY[v & 0x0F];
+        }
+        return new String(hexChars, StandardCharsets.UTF_8);
+    }
+}
diff --git a/src/main/java/com/riscure/trs/TRSFormatException.java b/src/main/java/com/riscure/trs/TRSFormatException.java
@@ -5,7 +5,11 @@ public TRSFormatException(String message) {
         super(message);
     }
 
-    public TRSFormatException(String formattedMessage, Object... values) {
-        super(String.format(formattedMessage, values));
+    public TRSFormatException(Throwable throwable) {
+        super(throwable);
+    }
+
+    public TRSFormatException(String message, Throwable throwable) {
+        super(message, throwable);
     }
 }
diff --git a/src/main/java/com/riscure/trs/TRSMetaData.java b/src/main/java/com/riscure/trs/TRSMetaData.java
@@ -1,6 +1,8 @@
 package com.riscure.trs;
 
 import com.riscure.trs.enums.TRSTag;
+import com.riscure.trs.parameter.trace.definition.TraceParameterDefinitionMap;
+import com.riscure.trs.parameter.traceset.TraceSetParameterMap;
 
 import java.util.HashMap;
 import java.util.Map;
@@ -103,6 +105,30 @@ public float getFloat(TRSTag tag) {
         return (Float) metaData.get(tag);
     }
 
+    /**
+     * Get the TraceSetParameters of this trace set, or an empty set if they are undefined
+     * @return the TraceSetParameters of this trace set
+     */
+    public TraceSetParameterMap getTraceSetParameters() {
+        Object o = metaData.get(TRSTag.TRACE_SET_PARAMETERS);
+        if (o instanceof TraceSetParameterMap) {
+            return (TraceSetParameterMap) o;
+        }
+        return new TraceSetParameterMap();
+    }
+
+    /**
+     * Get the TraceParameterDefinitions of this trace set, or an empty set if they are undefined
+     * @return the TraceParameterDefinitions of this trace set
+     */
+    public TraceParameterDefinitionMap getTraceParameterDefinitions() {
+        Object o = metaData.get(TRSTag.TRACE_PARAMETER_DEFINITIONS);
+        if (o instanceof TraceParameterDefinitionMap) {
+            return (TraceParameterDefinitionMap) o;
+        }
+        return new TraceParameterDefinitionMap();
+    }
+
     /**
      * Check whether the supplied tag has the default value in this metadata
      * @param tag the tag to check the data for

diff --git a/src/main/java/com/riscure/trs/TRSMetaDataUtils.java b/src/main/java/com/riscure/trs/TRSMetaDataUtils.java
@@ -1,10 +1,13 @@
 package com.riscure.trs;
 
 import com.riscure.trs.enums.TRSTag;
+import com.riscure.trs.parameter.trace.definition.TraceParameterDefinitionMap;
+import com.riscure.trs.parameter.traceset.TraceSetParameterMap;
 
 import java.io.FileOutputStream;
 import java.io.IOException;
 import java.nio.ByteBuffer;
+import java.nio.charset.StandardCharsets;
 
 public class TRSMetaDataUtils {
     private static final String IGNORED_UNKNOWN_TAG = "ignored unknown metadata tag '%02X' while reading a TRS file\n";
@@ -30,9 +33,9 @@ public static void writeTRSMetaData(FileOutputStream fos, TRSMetaData metaData)
             fos.write(tag.getValue());
             if (tag.getType() == String.class) {
                 String s = metaData.getString(tag);
-                int len = s.length();
-                writeLength(fos, len);
-                fos.write(s.getBytes());
+                byte[] stringBytes = s.getBytes(StandardCharsets.UTF_8);
+                writeLength(fos, stringBytes.length);
+                fos.write(stringBytes);
             } else if (tag.getType() == Float.class) {
                 float f = metaData.getFloat(tag);
                 writeLength(fos, tag.getLength());
@@ -44,8 +47,16 @@ public static void writeTRSMetaData(FileOutputStream fos, TRSMetaData metaData)
             } else if (tag.getType() == Integer.class) {
                 writeLength(fos, tag.getLength());
                 writeInt(fos, metaData.getInt(tag), tag.getLength());
+            } else if (tag.getType() == TraceSetParameterMap.class) {
+                byte[] serialized = metaData.getTraceSetParameters().serialize();
+                writeLength(fos, serialized.length);
+                fos.write(serialized);
+            } else if (tag.getType() == TraceParameterDefinitionMap.class) {
+                byte[] serialized = metaData.getTraceParameterDefinitions().serialize();
+                writeLength(fos, serialized.length);
+                fos.write(serialized);
             } else {
-                throw new TRSFormatException(UNSUPPORTED_TAG_TYPE, tag.getName(), tag.getType());
+                throw new TRSFormatException(String.format(UNSUPPORTED_TAG_TYPE, tag.getName(), tag.getType()));
             }
         }
         fos.write(TRSTag.TRACE_BLOCK.getValue());
@@ -76,7 +87,7 @@ private static void writeLength(FileOutputStream fos, long length) throws IOExce
      * @throws TRSFormatException If either the file is corrupt or the reader is not positioned at the start of the file
      */
     public static TRSMetaData readTRSMetaData(ByteBuffer buffer) throws TRSFormatException {
-        TRSMetaData trs = new TRSMetaData();
+        TRSMetaData trs = TRSMetaData.create();
         byte tag;
 
         //We keep on reading meta data until we hit tag TB=0x5f
@@ -122,8 +133,12 @@ private static void readAndStoreData(ByteBuffer buffer, byte tag, int length, TR
             trsMD.put(trsTag, readBoolean(buffer));
         } else if (trsTag.getType() == Integer.class) {
             trsMD.put(trsTag, readInt(buffer, length));
+        } else if (trsTag.getType() == TraceSetParameterMap.class) {
+            trsMD.put(trsTag, readTraceSetParameters(buffer, length));
+        } else if (trsTag.getType() == TraceParameterDefinitionMap.class) {
+            trsMD.put(trsTag, readTraceParameterDefinitions(buffer, length));
         } else {
-            throw new TRSFormatException(UNSUPPORTED_TAG_TYPE, trsTag.getName(), trsTag.getType());
+            throw new TRSFormatException(String.format(UNSUPPORTED_TAG_TYPE, trsTag.getName(), trsTag.getType()));
         }
     }
 
@@ -149,6 +164,28 @@ private static String readString(ByteBuffer buffer, int length) {
         byte[] ba = new byte[length];
         buffer.get(ba);
 
-        return new String(ba);
+        return new String(ba, StandardCharsets.UTF_8);
+    }
+
+    private static TraceSetParameterMap readTraceSetParameters(ByteBuffer buffer, int length) throws TRSFormatException {
+        byte[] ba = new byte[length];
+        buffer.get(ba);
+
+        try {
+            return TraceSetParameterMap.deserialize(ba);
+        } catch (IOException e) {
+            throw new TRSFormatException(e);
+        }
+    }
+
+    private static TraceParameterDefinitionMap readTraceParameterDefinitions(ByteBuffer buffer, int length) throws TRSFormatException {
+        byte[] ba = new byte[length];
+        buffer.get(ba);
+
+        try {
+            return TraceParameterDefinitionMap.deserialize(ba);
+        } catch (IOException e) {
+            throw new TRSFormatException(e);
+        }
     }
 }