updated comments, minor fixes and refactorings

src/net/pwendland/javacard/pki/DedicatedFile.java

@@ -51,16 +51,16 @@ public class DedicatedFile extends File {
     /**
      * \brief Instantiate a new DedicatedFile.
      *
+     * \param fileID The file ID. Should be unique inside the filesystem.
+     *
      * \param fileControlInformation The array of bytes containing the valid (!) File Control Information.
      *				It must contain the File ID (Tag 83). No Copy is made.
      *
      * \attention No copy of the FCI is made. Do not pass any buffer that is altered
      *				later (e.g. the apdu buffer). Max length 257 bytes as the length
      *				of the FCI Tag (6F) must be a byte.
      *
-     * \attention To be safe, use FileFactory.getSafeFile() to instantiate files.
-     *
-     * \throw  IllegalArgumentException If necessary tags in the FCI are missing.
+     * \attention To be safe, use IsoFilesystem.getSafeFile() to instantiate files.
      *
      * \return The DedicatedFile.
      */
@@ -73,6 +73,12 @@ public DedicatedFile(short fileID, byte[] fileControlInformation) {
     /**
      * \brief Check if this is the name of this DedicatedFile.
      *
+     * \param name The array containing the name to compare with the file's name.
+     *
+     * \param offset The offset at where the name begins.
+     *
+     * \param length The length of the name.
+     *
      * \return false if the DF has no name or the names do not match,
      *			true else.
      */
@@ -84,11 +90,12 @@ public boolean isName(byte[] name, short offset, short length) {
             return false;
         } else {
             // This DF has a name.
-            if(length != (short) fci[(short)(namePos+1)]) {
+            if(length != UtilTLV.decodeLengthField(fci, (short)(namePos+1))) {
                 // The names do not have equal length.
                 return false;
             } else {
-                return ( (byte)0 == Util.arrayCompare(name, offset, fci, (short)(namePos+2), (short)(fci[(short)(namePos+1)])) );
+                return ( (byte)0 == Util.arrayCompare(name, offset, fci,
+                                                      (short)(namePos+1+UtilTLV.getLengthFieldLength(length)), length) );
             }
         }
     }
@@ -105,16 +112,18 @@ public byte getChildrenCount() {
     /**
      * \brief Get a children of this Dedicated File.
      *
-     * This method returns the specified children of this DF.
+     * This method returns the specified children of this DF. Can be used in conjunction with getChildrenCount()
+     * to iterate over all children.
      *
-     * \param num The number of the children. This number references to the order in which the child was added.
+     * \param num The number of the children, starting at 0 to getChildrenCount(). The references can change when
+     *				children had been deleted.
      *
      * \throw FileNotFoundException If the specified file was not found unter this DF.
      *
      * \return The children file if present. May be a DedicatedFile or any non-abstract ElementaryFile subclass.
      */
     public File getChildren(byte num) throws FileNotFoundException {
-        if(num > this.currentNumChildren) {
+        if(num >= this.currentNumChildren) {
             throw FileNotFoundException.getInstance();
         }
         return children[num];
@@ -148,11 +157,12 @@ public void deleteChildren(short fileID) throws FileNotFoundException {
         currentNumChildren--; // We have one less children now.
 
         // Fill up empty field in children array.
+        // The last children is one ahead, so it is at currentNumChildren.
         if(childNum < currentNumChildren) {
             children[childNum] = children[currentNumChildren];
         }
 
-        // Clean up garbage.
+        // Clean up the old file object.
         JCSystem.requestObjectDeletion();
     }
 
@@ -166,25 +176,24 @@ public void deleteChildren(short fileID) throws FileNotFoundException {
     public void addChildren(File childFile) throws NotEnoughSpaceException {
         // First we have to check for enough space.
         if(currentNumChildren >= (short)children.length) {
+            File[] newChildren = null;
             // The array is full - we try to increase the size.
             if((short)(children.length * 2) <= CHILDREN_COUNT_MAX) {
                 // Doubling the size is possible.
-                File[] newChildren = new File[(short)(children.length * 2)];
+                newChildren = new File[(short)(children.length * 2)];
                 copyFileArrayRefs(children, newChildren);
-                children = newChildren; // Initial children array is now garbage.
-                JCSystem.requestObjectDeletion();
             } else {
                 // Doubling not possible - try to at least increase to CHILDREN_COUNT_MAX.
                 if(currentNumChildren < CHILDREN_COUNT_MAX) {
-                    File[] newChildren = new File[CHILDREN_COUNT_MAX];
+                    newChildren = new File[CHILDREN_COUNT_MAX];
                     copyFileArrayRefs(children, newChildren);
-                    children = newChildren; // Initial children array is now garbage.
-                    JCSystem.requestObjectDeletion();
                 } else {
                     // CHILDREN_COUNT_MAX exceeded. No "space" left. Fail.
                     throw NotEnoughSpaceException.getInstance();
                 }
             }
+            children = newChildren; // Initial children array is now garbage.
+            JCSystem.requestObjectDeletion();
         } // We have enough space (now).
         children[currentNumChildren++] = childFile;
         return;
@@ -202,7 +211,9 @@ public void addChildren(File childFile) throws NotEnoughSpaceException {
      */
     private static void copyFileArrayRefs(File[] src, File[] dest) {
         short i = 0;
-        for(i=0; i < src.length; i++) {
+        short length = src.length > dest.length ? (short)dest.length : (short)src.length;
+
+        for(i=0; i < length; i++) {
             dest[i] = src[i];
         }
         return;
@@ -250,7 +261,7 @@ public ElementaryFile findChildElementaryFileBySFI (byte sfi) throws FileNotFoun
             throw FileNotFoundException.getInstance();
         }
         short i;
-        for(i=0; i< currentNumChildren; i++) {
+        for(i=0; i < currentNumChildren; i++) {
             if(children[i] instanceof ElementaryFile &&
                     ((ElementaryFile)children[i]).getShortFileID() == sfi) {
                 return (ElementaryFile) children[i];
@@ -383,7 +394,7 @@ public File findChildrenByPath(byte[] path, short pathOffset, short pathLength)
                         df = (DedicatedFile) df.getChildren( childPos);
                         break;
                     } else {
-                        // matching file ID, has children according to path, but is no DF.
+                        // Matching file ID, has children according to path, but is no DF.
                         // Something really bad happened or the path was invalid!
                         throw FileNotFoundException.getInstance();
                     }

src/net/pwendland/javacard/pki/ECCurves.java

@@ -19,6 +19,9 @@
 
 package net.pwendland.javacard.pki;
 
+/**
+ * \brief A helper class containing EC parameters.
+ */
 public abstract class ECCurves {
     public static final short LENGTH_EC_FP_256 = 256;
 
@@ -77,8 +80,8 @@ public abstract class ECCurves {
     };
     public static final short EC_BRAINPOOLP192R1_PARAM_K  = (short) 1; // Cofactor - "h"
 
-    /* secp256r1 / prime256v1 */
 
+    /* secp256r1 / prime256v1 */
     public static final byte[] EC_PRIME256V1_PARAM_P = {
         (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF,
         (byte) 0x00, (byte) 0x00, (byte) 0x00, (byte) 0x01,

src/net/pwendland/javacard/pki/ElementaryFile.java

@@ -31,15 +31,15 @@ public abstract class ElementaryFile extends File {
      * \brief Abstract constructor to be called by subclasses.
      *
      * \param fileControlInformation The array of bytes containing the valid (!) File Control Information.
-     *				It must contain the File ID (Tag 83). No Copy is made.
+     *									No Copy is made.
+     *
+     * \param fileID The ID of the file. Consistency with tag 0x83 from the FCI is NOT checked.
      *
      * \attention No copy of the FCI is made. Do not pass any buffer that is altered
      *				later (e.g. the apdu buffer). Max length 257 bytes as the length
      *				of the FCI Tag (6F) must be a byte.
      *
-     * \attention To be safe, use FileFactory.getSafeFile() to instantiate files.
-     *
-     * \throw IllegalArgumentException If necessary tags in the FCI are missing.
+     * \attention To be safe, use IsoFileSystem.getSafeFile() to instantiate files.
      */
     public ElementaryFile(short fileID, byte[] fileControlInformation) {
         super(fileID, fileControlInformation);
@@ -48,7 +48,7 @@ public ElementaryFile(short fileID, byte[] fileControlInformation) {
     }
 
     /**
-     * \brief Get the short file ID (SFI).
+     * \brief Get the short file Identifier (SFI).
      *
      * \return The SFI.
      */

src/net/pwendland/javacard/pki/ElementaryFileCyclicFixed.java

@@ -30,8 +30,10 @@ public class ElementaryFileCyclicFixed extends ElementaryFileLinearFixed {
     /**
      * \brief Instantiate a new cyclic EF (fixed record size). No data is being added at this point.
      *
+     * \param fileID The ID of the file.
+     *
      * \param fileControlInformation The array of bytes containing the valid (!) File Control Information.
-     *				It must contain the File ID (Tag 83). No Copy is made.
+     *				No Copy is made.
      *
      * \param maxRecords The maximum amount of saved records before overwriting happens.
      *
@@ -41,7 +43,7 @@ public class ElementaryFileCyclicFixed extends ElementaryFileLinearFixed {
      *				later (e.g. the apdu buffer). Max length 257 bytes as the length
      *				of the FCI Tag (6F) must be a byte.
      *
-     * \attention To be safe, use FileFactory.getSafeFile() to instantiate files.
+     * \attention To be safe, use IsoFilesystem.getSafeFile() to instantiate files.
      *
      * \throw IllegalArgumentException If necessary tags in the FCI are missing.
      */
@@ -53,25 +55,29 @@ public ElementaryFileCyclicFixed(short fileID, byte[] fileControlInformation, by
     /**
      * \brief Add a record to this cyclic EF (fixed record size).
      *
-     * \attention No record will be added if it is of the wrong size. No exception will be thrown either.
-     * Make sure that the record to add is of the correct length (e.g. by using getRecordLength() beforehand).
+     * \attention No record will be added if it is of the wrong size.
+     *		Make sure that the record to add is of the correct length (e.g. by using getRecordLength() beforehand).
      *
      * \attention As this file is cyclic, the oldest record might get overwritten.
      *
      * \param record The byte array containing the data to add. Must be of the right size.
+     *
+     * \return 	true 	If the record had been added.
+     *			false	An error occurred, no record had been added.
      */
     @Override
-    public void addRecord(byte[] record) {
+    public boolean addRecord(byte[] record) {
         if(record.length == super.getRecordLength()) {
             // Create a new record with the byte array as data and append it to the records array.
             records[currentRecordPos] = new Record(record);
             // Update the current position (cyclic/modulo operation).
             currentRecordPos = (byte)((currentRecordPos + (byte) 1) % (byte) records.length);
             // Only increase currentRecordCount if the array was not full before the operation.
             // (If it was full, the oldest record had been overwritten, so the amount of records did not change.)
-            currentRecordCount = currentRecordCount == (byte) records.length? currentRecordCount : (byte) (currentRecordCount + 1);
+            currentRecordCount = currentRecordCount == (byte) records.length ? currentRecordCount : (byte) (currentRecordCount + 1);
+            return true;
         }
-        return;
+        return false;
     }
 
 }

src/net/pwendland/javacard/pki/ElementaryFileLinearFixed.java

@@ -30,8 +30,10 @@ public class ElementaryFileLinearFixed extends ElementaryFileLinearVariable {
     /**
      * \brief Instantiate a new linear EF (fixed record size). No data is being added at this point.
      *
+     * \param fileID The ID of the file.
+     *
      * \param fileControlInformation The array of bytes containing the valid (!) File Control Information.
-     *				It must contain the File ID (Tag 83). No Copy is made.
+     *				No Copy is made.
      *
      * \param maxRecords The maximum amount of saved records.
      *
@@ -62,23 +64,29 @@ public short getRecordLength() {
     /**
      * \brief Add a record to this EF (fixed record size).
      *
-     * \attention No record will be added if it is of the wrong size. No exception will be thrown either.
-     * Make sure that the record to add is of the correct length (e.g. by using getRecordLength() beforehand).
+     * \attention No record will be added if it is of the wrong size.
+     * 		Make sure that the record to add is of the correct length (e.g. by using getRecordLength() beforehand).
      *
      * \attention Only references are being stored, no copy is made (for perfomance reasons).
      *
      * \param record The byte array containing the data to save.
+     *
+     * \return 	true 	If the record had been added.
+     *			false	An error occurred, no record had been added.
      */
     @Override
-    public void addRecord(byte[] record) throws NotEnoughSpaceException {
+    public boolean addRecord(byte[] record) {
         if(records.length == currentRecordCount) {
-            throw NotEnoughSpaceException.getInstance();
+            // No space left.
+            return false;
         }
         if(record.length == recordLength) {
             // Create a new Record with the byte array as data and append it to the records array, increasing currentRecordCount.
             records[currentRecordCount++] = new Record(record);
+            return true;
+        } else {
+            return false;
         }
-        return;
     }
 
 }

src/net/pwendland/javacard/pki/ElementaryFileLinearVariable.java

@@ -22,7 +22,7 @@
 /**
  * \brief The ElementaryFileLinearVariable class.
  *
- * It saves linear records of variable size.
+ * It stores linear records of variable size.
  *
  * \todo Find record methods?
  */
@@ -64,17 +64,18 @@ public byte getCurrentRecordCount() {
     /**
      * \brief Add a record.
      *
-     * \throws NotEnoughSpaceException If the maximum amount of records is exceeded.
-     *
      * \param record The data to save as record.
+     *
+     * \return 	true 	If the record had been added.
+     *			false	An error occurred, no record had been added.
      */
-    public void addRecord(byte[] record) throws NotEnoughSpaceException {
+    public boolean addRecord(byte[] record) {
         if(records.length == currentRecordCount) {
-            throw NotEnoughSpaceException.getInstance();
+            return false;
         }
         // Create a new Record with the byte array as data and append it to the records array, increasing currentRecordCount.
         records[currentRecordCount++] = new Record(record);
-        return;
+        return true;
     }
 
     /**

src/net/pwendland/javacard/pki/ElementaryFileTransparent.java

@@ -31,7 +31,7 @@ public class ElementaryFileTransparent extends ElementaryFile {
      * \brief Instantiate a new transparent EF and store a reference to the data.
      *
      * \param fileControlInformation The array of bytes containing the valid (!) File Control Information.
-     *				It must contain the File ID (Tag 83). No Copy is made.
+     *				No Copy is made.
      *
      * \param data The byte array to be saved. No copy is made, only a reference is stored.
      *
@@ -53,8 +53,10 @@ public ElementaryFileTransparent(short fileID, byte[] fileControlInformation, by
      *
      * No actual data is being added at this point. Call getData() the get a reference and fill the array.
      *
+     * \para, fileID The ID of the file.
+     *
      * \param fileControlInformation The array of bytes containing the valid (!) File Control Information.
-     *				It must contain the File ID (Tag 83). No Copy is made.
+     *				No Copy is made.
      *
      * \param dataLength The length of the data array to allocate.
      *