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 operationand  '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.kabwhere kabtool is to trigger the kabtool application under command promptand '-l' is the operation used to list the contents of the specified KAB fileand '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.kabwhere kabtool is to trigger the kabtool application under command promptand '-x' is the operation used to extract the contents of the specified KAB fileand '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.kabwhere kabtool is to trigger the kabtool application under command promptand '-c' is the operation used to check the digital signatures of the specified KAB fileand '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 2048Enter pass phrase for private.pem:Verifying - Enter pass phrase for private.pem:where 'openssl' is to trigger the openssl application under command promptand 'genrsa' is used to generate a public/private key pairand 'out' is used to Output the key to the specified fileand 'private.pem' is used as the specified output file nameand '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 -nocryptwhere 'openssl' is to trigger the openssl application under command promptand 'pkcs8' is used to provide pkcs8 format private key conversion tooland '-topk8' is used to provide the output file name in PKCS8 formatand '-inform' is used to provide the input formatand 'PEM' is used to provided input file in PEM formatand '-outform' is used to provide the output formatand 'DER' is used to provide output file in DER formatand '-in' is used to provide the input file nameand 'private.pem' is the provided input file in PEM formatand '-out' is used to provide the output file nameand 'private.der' is the provided outputfile in DER formatand '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.derEnter pass phrase for private.pem:where 'openssl' is to trigger the openssl application under command promptand 'rsa' is used as rsa key processing commandand '-in' is used to provide the input file nameand 'private.pem' is the provided input file in PEM formatand '-pubout' is used to output the public keyand '-outform' is used to provide the output formatand 'DER' is used to provided output file in DER formatand '-out' is used to provide the output file nameand '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.kabwhere 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: