KOS Developer's Portal

kabTool

Overview

When working with KOS, virtually everything is packaged as a KAB file. While KOS Studio provides infrastructure for working with KAB files, including a KAB viewer that allows preview and extraction of KAB contents, at some point developers need to work with their own KAB files in environments that are more command line oriented. To address this, KOS Studio includes kabtool, a command line tool that can create and manipulate KAB files, which can be used in automation scripts and build servers.

Concepts

Several key concepts must be understood when working with KAB files and the kabtool command-line tool. Many of these are covered in more detail here. This section briefly covers some of these core concepts.

Collection of files

A KAB file is logically just a file that contains a collection of files, much like a zip file. Every KAB file is digitally signed and includes meta-data in the KAB header. The kabtool command line tool creates a KAB file from a zip file. This allows existing zip-related tools to construct the correct set of content for the KAB. Within KOS, it is possible to examine the files in a KAB and even mount a KAB into the native filesystem as if it is a virtual disk.

Header fields

Every KAB file contains several key fields in the header. Some of these fields play important roles within KOS, while others can be used for developer-specific needs. Here is a brief description of these fields and their expected role:

identity

Every KAB file is generated with a unique identity in the form of a UUID. Within KOS, two KAB files with the same identity are considered to be identical. This is reflected in kabtool, as it provides no way to specify the identifier. Any solution that requires control over the generated identity of a KAB violates this core premise of KOS.

type

The type is typically the primary method of identifying the purpose of a KAB. There are a number of standard KAB types within KOS, and they will all begin with the “kos.” prefix. Developers are free to define new types, but should use a consistent namespace prefix for their organization to avoid creating types that overlap with other organizations.

name

By default, this is the name of the file from which the KAB was generated, but developers are free to use the name field to suite their needs, as KOS internals do not use this field.

tag

When publishing a KAB using publishtool , if a qualifier is not specified on the command line, the tag field will be used as the qualifier. When used this way, any KAB can be examined to understand the platforms the KABis compatible with. This is not required and once published, KOS internals will not examine the tag field. This allows developers to use the tag field as supplemental information, typically in combination with the type field.

version

A user-provided version for the KAB. While this can be a free-form string, KOS Studio treats all version strings as semantic versions. KOS Studio provides advanced virtual version functionality which can only be used when using proper semver versions.

Descriptor

While a KAB is simply a packaged collection of files, KOS provides standard support for a file named descriptor.json in the root directory of the KAB. This json file is commonly used as a standard way to provide additional information about the contents of the KAB that otherwise can’t be placed in the KAB header. For example, the KOS application loader expects descriptor.json to contain information about the application class name and application id. When building a KABfor a particular purpose, be sure to understand if there is a requirement for the KAB to contain a descriptor with specific information. Developers are free to leverage the descriptor infrastructure for their own needs.

Encryption

While KAB files are digitally signed and verified when used, the contents of the KAB are clear text. There is support for public / private key encryption of KAB contents at the per-file level. This requires providing a private key during KABcreation and flagging which files should be encrypted (kabtool will encrypt all files when encryption is enabled). Similarly, KAB files with encrypted content require a public key to extract the encrypted content. KAB entries are flagged as encrypted and extracting the content of an encrypted file without a public key will simply return the encrypted content.

Publishing

When working within a group, the complexity of managing and sharing locally built KAB files introduces considerable overhead into the development process. KOS Studio eliminates this through a process called publishing. This allows a build server to notify KOS Studio about the latest build and allows the KOS tooling to fetch the correct KAB files without the need to transfer them to team members manually.

Usage

For KOS, everything is a KAB file and it provides the kabtool as a kab creator/viewer/extractor tool. All the artifacts or deliverables (for ui or backend) generated for KOS must be created in *.kab format.

During the create operation, it requires the keyset shipped with KOS Studio to generate and view the contents of the built kab. Again, kabtool comes in handy to know the contents of the file. Moreover, to unpackage the kab, a tool is used to extract the contents into the local filesystem.

Once the KAB file is built via the local or build pipeline process, sharing the KABs requires us to Publish a KAB; find out more here.

Kabtool allows to perform various operations such as:

listing the contents of a kab
to examine the various header details of the kab (type, name, tag…)
to extract the contents of a kab to the local file system
to build a kab with encrypted contents
to extract a kab of encrypted contents

Command formats

General

$ kabtool [-operation] [-options] [kabfile]
where 'operation' is one of [b, c, l, x] => [build, check, list, extract]
and  'options'   depends on the selected operation
and  'kabfile'   is the name of the KAB file to either create or operate on

List the contents of a KAB archive

The user should provide the values as kabtool name, [-l option] & the kab file as shown below :

$ kabtool -l MyFile.kab
where kabtool is to trigger the kabtool application under command prompt
and '-l' is the operation used to list the contents of the specified KAB file
and 'MyFile.kab' is the kab file used to list the contents

Extract the contents from a KAB archive

The user should provide the values as kabtool name, [-x option] & the kab file as shown below :

$ kabtool -x MyFile.kab
where kabtool is to trigger the kabtool application under command prompt
and '-x' is the operation used to extract the contents of the specified KAB file
and 'MyFile.kab' is the kab file used to extract the contents

Check the digital signature of a KAB archive

The user should provide the values as kabtool name, [-c option] & the kab file as shown below :

$ kabtool -c MyFile.kab
where kabtool is to trigger the kabtool application under command prompt
and '-c' is the operation used to check the digital signatures of the specified KAB file
and 'MyFile.kab' is the kab file used to check the KAB file's digital signature

Create public/private keys pairs

The user should provide the values as openssl name, genrsa tool, [output file name & bits options] for the key pair generation as shown below :

Generate a 1024 bit private key

$ openssl genrsa -out private.pem 2048
Enter pass phrase for private.pem:
Verifying - Enter pass phrase for private.pem:
where 'openssl' is to trigger the openssl application under command prompt
and 'genrsa' is used to generate a public/private key pair
and 'out' is used to Output the key to the specified file
and 'private.pem' is used as the specified output file name
and '2048' is used to generate 2048-bit key

private.der key will be created under users home directory
- For Windows: C:\Users\myhome>
- For Mac: /Users/myhome
  - Convert private key to PKCS8 format The user should provide the values as openssl name, pkcs8 tool, [input file name, input format, in, output file name, output format, out, nocrypt options] for the private key conversion as shown below :

$ openssl pkcs8 -topk8 -inform PEM -outform DER -in private.pem -out private.der -nocrypt
where 'openssl' is to trigger the openssl application under command prompt
and 'pkcs8' is used to provide pkcs8 format private key conversion tool
and '-topk8' is used to provide the output file name in PKCS8 format
and '-inform' is used to provide the input format
and 'PEM' is used to provided input file in PEM format
and '-outform' is used to provide the output format
and 'DER' is used to provide output file in DER format
and '-in' is used to provide the input file name
and 'private.pem' is the provided input file in PEM format
and '-out' is used to provide the output file name
and 'private.der' is the provided outputfile in DER format
and 'nocrypt' is the to provide the unencrypted private key

private.pem key will be created under users home directory
- For Windows:C:\Users\myhome>
- For Mac:/Users/myhome
  - Output public key to extract the public key in DER format The user should provide as openssl name, rsa tool, [input file name, input format, in, output file name, output format, out, nocrypt options] for the output public key generation as shown below :

$ openssl rsa -in private.pem -pubout -outform DER -out public.der
Enter pass phrase for private.pem:
where 'openssl' is to trigger the openssl application under command prompt
and 'rsa' is used as rsa key processing command
and '-in' is used to provide the input file name
and 'private.pem' is the provided input file in PEM format
and '-pubout' is used to output the public key
and '-outform' is used to provide the output format
and 'DER' is used to provided output file in DER format
and '-out' is used to provide the output file name
and 'public.der' is the provided outputfile in DER format

public.der key will be created under users home directory
- For Windows:C:\Users\myhome>
- For Mac:/Users/myhome
  - Build the kabfile from a zipfile & private key The user should provide kabtool name, [-b, -e, -t, -q, -n, -v, -k, -z option] & the filename for the kab generation as shown below :

 $ kabtool -b -e=private.der -t=MyType -q=MyQual -n=MyName -v=1.2.3 \
  -k=/secrets/MyKeyset.keys -z=/data/MyBuild.zip MyOutput.kab
where kabtool is to trigger the kabtool application under command prompt
    and '-b' is the operation used to build the KAB file from the given ZIP file
    and '-e' is the options used to encryption private key used to build a KAB specified KAB file
    and 'private.der' is the private key provided in PKCS8 format
    and '-t' is the options used to specify type of KAB file
    and 'MyType' is the provided kab type value
    and '-q' is the options used to specify user defined tag of KAB file
    and 'MyQual' is the provided qualifier name for the KAB file
    and '-n' is the options used to specify name of KAB file
    and 'MyName' is the provided of KAB file name
    and '-v' is the options used to specify version of KAB file
    and '1.2.3' is the provided version in semver format or non-semver string.
    and '-k' is the options used to provide the full path to the keyset file used for signing
    and '/secrets/MyKeyset.keys' is the provided full path to the keyset file
    and '-z' is the options used to provide the full path to the ZIP file used to build a KAB
    and '/data/MyBuild.zip' is the provided full path to the ZIP file
    and  'MyOutput.kab' is the specified output kab file name

Publish the built kab

To publish the kab follow Publishing a kab

Command options summary:

Table 1. kabTool Command Options Summary
Short Option	Long Option	Description
-a	--display-all	Display all output when listing (-l) contents
-b,	--build	Build the KAB file from the given ZIP file
-c,	--check	Check the KAB file’s digital signature
-d,	--decrypt <public.der>	Decryption public key used to extract a KAB
-e,	--encrypt <private.der>	Encryption private key used to build a KAB
-h,	--help	Show this help page
-k	--keyset-file <keyset.keys>	Full path to the keyset file used for signing
-l,	--list	List the contents of the KAB file
-n	--name <kab-name> --prop-file <arg>	Specify 'name' of KAB file. This is typically used to store a user readable name of the Kab for display.
-n	--prop-file <arg>	Use a file other than ~/kosStudio/tools.properties to lookup defaults
-q,	--tag <kab-qual>	Specify user defined 'tag' of KAB file. A user defined tag that can be used in conjunction with type to identify the Kab.
-t,	--type <kab-type>	Specify 'type' of KAB file. 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.
-v,	--version <kab-version>	Specify 'version' of KAB file using any semver compatible version or non-semver string
-x	--extract	Extract the contents of the KAB file
-z,	--zip-file <file.zip>	Full path to the ZIP file used to build a KAB