Package com.tccc.kos.commons.kab

Class KabFile

java.lang.Object
com.tccc.kos.commons.kab.KabFile
public class KabFile extends Object
Opens an existing archive file and provides access to its contents. The archive file format is as follows. All 16- and 32-bit values are stored big-endian. Values that are larger than 32 bits are divided into ascending 32-bit values as shown below. Strings are encoded in UTF-8 without null termination.

The body contains the archive entries, which are just the archived files packed end-to-end. When all entries are written, the directory marker is inserted, the directory entries are written, and the offset from the end of the file to the directory marker is written. Finally, the digital signature is added. When loading an archive file, the directory is located by skipping the signature, reading the directory offset, and checking that it points to the marker.

Archive files are limited to 2GB, as they use 32-bit internal offsets. Given that archive files are generally expected to be deployed over the air, this should not be a significant constraint. 

 +--------------------+--------------------+---------------------+--------------------+
 |        'K'         |         'A'        |          'B'        |         \0         |
 +--------------------+--------------------+---------------------+--------------------+
 |   header version   |      reserved      |
 +--------------------+--------------------+
 |              header length              |
 +--------------------+--------------------+
 |            identifier length            |
 +--------------------+--------------------+
 |                type length              |
 +--------------------+--------------------+
 |                 tag length              |
 +--------------------+--------------------+
 |                name length              |
 +--------------------+--------------------+
 |               certs length              |
 +--------------------+--------------------+
 |              version length             |
 +--------------------+--------------------+
 |                reserved                 |
 +--------------------+--------------------+
 |                reserved                 |
 +--------------------+--------------------+
 |                reserved                 |
 +--------------------+--------------------+
 |                reserved                 |
 +--------------------+--------------------+---------------------+--------------------+
 |                                 Create time 0..31                                  |
 +--------------------+--------------------+---------------------+--------------------+
 |                                 Create time 32..64                                 |
 +--------------------+--------------------+---------------------+--------------------+
 | identifier string  |                          |  identifier len
 |        ...         |                          |
 +--------------------+                        --+
 |    type string     |                          |  type len
 |        ...         |                          |
 +--------------------+                        --+
 |     tag string     |                          |  tag len
 |        ...         |                          |
 +--------------------+                        --+
 |    name string     |                          |  name len
 |        ...         |                          |
 +--------------------+                        --+
 |    version bytes   |                          |  version len
 |        ...         |                          |
 +--------------------+                        --+
 |     certs bytes    |                          |  certs len
 |        ...         |                          |
 +--------------------+                        --+
 |     file data      |
 |        ...         | <-------- all the files added to the kab
 |        ...         |
 +--------------------+                        --+
 |  directory entries |                          |  directory len
 |        ...         |                          |
 +--------------------+                        --+
 |    symbol table    |                          |  symbol table len
 |        ...         |                          |
 +--------------------+--------------------+   --+
 |             symbol table len            |
 +--------------------+--------------------+
 |           directory entry count         |
 +--------------------+--------------------+---------------------+--------------------+
 |                                  directory len                                     |
 +--------------------+--------------------+---------------------+--------------------+
 |        0x44        |       0x33         |        0x22         |       0x11         | <-- eof marker
 +--------------------+--------------------+---------------------+--------------------+
 |                                        ...                                         |
 |                        digital signature of entire contents (256 bytes)            |
 |                                        ...                                         |
 +--------------------+--------------------+---------------------+--------------------+
Since:
1.0
Version:
2022-09-21

  • Field Details

  • Constructor Details

    • KabFile

      public KabFile(File file) throws IOException
      Open the specified file as an archive file.
      Parameters:
      file - the underlying archive file
      Throws:
      IOException - if there is an underlying file error

    • KabFile

      public KabFile(File file, int start, int len) throws IOException
      Open the specified file and use just a subset of the file as an archive file. This is handy when an archive file is packed inside another file. By tracking start/end offsets, this can be used to open kab files nested arbitrarily deep.
      Parameters:
      file - the underlying archive file
      start - the start position of the archive
      len - the length of the archive
      Throws:
      IOException - if there is an underlying file error

  • Method Details

    • setDecryptionKey

      public void setDecryptionKey(PublicKey publicKey) throws IOException
      Set the decryption key to use for encrypted files within the kab. This must be the public key corresponding to the private key that was used to build the kab.
      Throws:
      IOException

    • hasEncrypted

      public boolean hasEncrypted()
      Returns true if the kab contains encrypted entries.

    • getMiniHash

      public String getMiniHash()
      Return the mini hash of the kab file using the default algorithm. As the algorithm can change over time, mini hashes should not be compared. Instead, pass a mini hash to verifyMiniHash() which will perform the comparison using the correct algorithm. This prevents all existing mini hashes from being invalidated if an improved algorithm is developed.

    • verifyMiniHash

      public void verifyMiniHash(String mhash) throws IOException
      Verify that the specified mini hash is valid for this file. Throws an exception if the hash is not applicable for this file. This is the only way to check a mini hash as the algorithm for mini hash may change over time so equality of hashes is not possible. This will identify the algorithm of the supplied hash and verify the file using that algorithm.
      Parameters:
      mhash - the mini hash to verify
      Throws:
      IOException

    • getHash

      public String getHash()
      Compute the sha-256 hash of the kab.

    • getIdentifier

      public String getIdentifier()
      Return the unique identifier of the KAB. Every KAB should have a globally unique identifier. KAB equality is determined by the identifier.
      Returns:
      The unique identifier of the KAB

    • getType

      public String getType()
      Return the type of the KAB. KAB types are hierarchical with kos.* reserved for kOS specific types. This identifies the type of the KAB and can be used to determine the function or contents of the KAB.
      Returns:
      The type of the Kab

    • getTag

      public String getTag()
      A user defined tag that can be used in conjunction with type to identify the KAB. For example, if @{company.cui} is used as a type, the tag can be used to identify the cui type, or which platform the cui can be used with. This is entirely at the discretion of developers and has no special purpose in kOS.
      Returns:
      The user defined tag

    • getName

      public String getName()
      The user defined name of the KAB. This is typically used to store a user readable name of the KAB for display.
      Returns:
      The user defined name of the KAB.

    • getVersion

      public String getVersion()
      The version of the KAB file. This should be a semver compatible version.
      Returns:
      The version of the KAB.

    • getVendorAuthority

      public String getVendorAuthority()
      Return the vendor authority of the KAB. This is derived from the key that was used to sign the KAB.
      Returns:
      The vendor authority of the KAB.

    • getMfgAuthority

      public String getMfgAuthority()
      Return the manufacturer authority of the KAB. This is derived from the key that was used to sign the KAB.
      Returns:
      The manufacturer authority of the KAB.

    • getMode

      public Mode getMode()
      Return the mode of the KAB. This is derived from the key that was used to sign the KAB. Test keys result in a test mode KAB whereas production keys result in a production mode KAB.
      Returns:
      The mode of the KAB.

    • verify

      public boolean verify()
      Verifies the KAB signature and then caches the result. Additional calls will return the cached result.

    • verifyDates

      public void verifyDates() throws IOException
      Verify the dates of the certPath. This is a separate call as we generally only check dates during the installation process so that if certs expire we continue to run already installed kabs but won't install new kabs that have expired. Throws IOExcepetion if the dates aren't valid.
      Throws:
      IOException

    • verifySignature

      public void verifySignature() throws IOException
      Verify the digital signature of the file. Throws IOException if validation fails.
      Throws:
      IOException

    • verifyVendorAuthority

      public void verifyVendorAuthority(String authority) throws IOException
      Verify the vendor authority of the file. If authority doesn't match then throw IOException.
      Parameters:
      authority - the authority to match
      Throws:
      IOException

    • verifyMfgAuthority

      public void verifyMfgAuthority(String authority) throws IOException
      Verify the manufacturer authority of the file. If authority doesn't match then throw IOException.
      Parameters:
      authority - the authority to match
      Throws:
      IOException

    • verifyType

      public void verifyType(String type) throws IOException
      Verify the type of the file. If type doesn't match then throw IOException.
      Parameters:
      type - the authority to match
      Throws:
      IOException

    • getRootEntry

      public KabEntry getRootEntry()
      Return the root entry for the kab

    • containsFile

      public boolean containsFile(String path)
      Indicates if the archive contain the requested file
      Parameters:
      path - path to the file
      Returns:
      check result

    • getInputStream

      public InputStream getInputStream(String path)
      Return an InputStream for the specified file within the archive. Returns null if the file is not found or the file is a directory.
      Parameters:
      path - the path of the file
      Returns:
      input stream to the specified file within the archive

    • getDescriptorInputStream

      public InputStream getDescriptorInputStream()
      Return the optional descriptor file as an input stream
      Returns:
      input stream for the descriptor file or null

    • getInputStream

      public InputStream getInputStream(KabEntry entry)
      Return an InputStream for the specified kab entry.
      Parameters:
      entry - the entry to return an input stream for
      Returns:
      input stream to the specified entry or null if the entry is a directory

    • getEntry

      public KabEntry getEntry(String name)
      Returns the named directory entry.
      Returns:
      entry or null

    • getEntries

      public Collection<KabEntry> getEntries()
      Returns a collection of entries contained in the archive
      Returns:
      entry collection

    • getEntries

      public List<KabEntry> getEntries(String basePath)
      Returns a list of entries contained in the archive with the specified base path.
      Parameters:
      basePath - the base path
      Returns:
      list of entries with the base path

    • getDescriptor

      public JsonDescriptor getDescriptor()
      Return the optional descriptor from the kab. If no descriptor exists this will still return an empty descriptor object, but it will not contain any data.
      Returns:
      the descriptor

    • getCreateDate

      public Date getCreateDate()
      Return the create date.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getFile

      public File getFile()

    • getSize

      public int getSize()

    • getCreateTime

      public long getCreateTime()

    • getCertPath

      public CertPath getCertPath()