Link Search Menu Expand Document

Raptor Package Manager - Package Manager Commands

Jan 1 2022 at 12:00 AM

  1. Overview
  2. Template - Create directory template used to compile driver packages
  3. Signing - Securing packages content files with a digital signature.
  4. Verify - Verifying package digital signature.
  5. Compile - Compile package info and deployment files into a Nuget package.
  6. Distribute - Distribute, upload, the NuGet package to the device store.
  7. Consolidate command to Sign; Compile and Distribute packages

Package manager commands are related to signing, verify, compiling and/or distributing driver/device packages.

Overview

Publishing the deployment configuration and associated package information after driver development has been done, is a crucial part of exposing the driver for deployment. The following commands are focused on the processes to secure, compile and distribute these packages.

Within the device store, device drivers are made available for deployment. The device store is a running BaGet repository instance where we have two NuGet packages types per device driver described as:

  1. Package Information, or Driver Information, and
  2. Deployment Configuration.

Using the Teltonika driver as an example, and as per the currently implementation, these packages can be identified as follows:

1. IoTnxt.Raptor.Device.Teltonika.UI - Package Information 
    1.1. Data\PackageInfo.json    

2. IoTnxt.Raptor.Device.Teltonika.UI.Meta - Deployment Configuration
    2.1. Content\deployment.json

To ensure that these files has been tampered with during upload to the device store or downloaded from the device store, these files has to be secured. Securing the files in this instance is the process of applying a digital signature to the files prior to compiling into a NuGet package format.

A digital signature ensures that the package content files, packageinfo.json and/or deployment.json, originates from where they state they do, and ensures credibility/integrity of file content.

Now that we have a little background on the security implementation. Let’s have a look at the available commands we have for the package manager.

Execute

raptorpm packagemanager  -h

Output

packagemanager:
  Commands related to managing packages for device store

Usage:
  raptorpm packagemanager [options] [command]

Options:
  Verbose, -v       Option to specify if command should be logged in detail
  -?, -h, --help    Show help and usage information

Commands:
  sign <Input> <SubjectName>                            Digitally sign a package by X509 certificate subject name.
  verify <Input> <SubjectName>                          Verify the signed package by X509 certificate subject name.
  compile <Input> <ProfileName>                         Compile a distribution package by author profile id
  distribute <Input> <ProfileName> <DeviceStoreName>    Command to distribute package by device store profile
  template                                              Command related to assist in getting started with a driver package template

The following commands will be discussed:

  • sign - Digitally sign a package by X509 certificate subject name.
  • verify - Verify the signed package by X509 certificate subject name.
  • compile - Compile a distribution package by author profile id.
  • distribute - Command to distribute package by device store profile.
  • template - Command related to assist in getting started with a driver.

Template - Create directory template used to compile driver packages

The template command helps to setup the directory structure which is currently used to compile a driver package in the correct format.

Execute

raptorpm packagemanager template create -h

Output

create:
  Command to assist in creating driver package template used for distribution

Usage:
  raptorpm packagemanager template create [options]

Options:
  DriverName, -n <DriverName>    Option to specify a driver name value.
  Version, -s <Version>          Option to specify a version value.
  Verbose, -v                    Option to specify if command should be logged in detail
  -?, -h, --help                 Show help and usage information

Sample execute

raptorpm packagemanager template create -n "IoTnxt.Raptor.Device.Teltonika" -s "4.0.21.1-rc"

Sample output

Successfully created template for : IoTnxt.Raptor.Device.Teltonika.v.4.0.21.1-rc

Using the driver folder template, the driver’s package folder will be created as follows:

{drivername}.v.{version}

Using the Teltonica driver as an example below:

IoTnxt.Raptor.Device.Teltonika.v.4.0.21.1-rc

The folder has the structure as below.

-IoTnxt.Raptor.Device.Teltonika.v.4.0.21.1-rc
    -Content
        -deployment.json
    -Data
        -PackageInfo.json
    -IotNxtIco.ico 
    -IotNxtIco.png

Note: that the Icon files are not created with the template. Also the .ico has to be within the root of the tempate directory to be embedded into the NuGet package on compile.

Sample from visual code

driverTemplateDirectory

Signing - Securing packages content files with a digital signature.

Signing package content files is simply the process of applying a digital signature to the file. The sign command requires the input path of the file we require to sign and then the subject name of the installed certificate. The private key on the certificate is used as the key to sign the file.

Execute

raptorpm packagemanager sign -h

Output

sign:
  Digitally sign a package by X509 certificate subject name.

Usage:
  raptorpm packagemanager sign [options] <Input> <SubjectName>

Arguments:
  <Input>          Provide the file path of the package to sign.
  <SubjectName>    Provide the X509 certificate subject name. This certificate will be used to sign the package

Options:
  OutputFilePath, -o <o>    Specify the full output file path and name of the file to use for the secured file.[default: ]
  Verbose, -v               Option to specify if command should be logged in detail
-?, -h, --help              Show help and usage information

Sample Usage

raptorpm packagemanager sign "C:\Demo\IoTnxt.Raptor.Device.Teltonika.v.4.0.21.1-rc\Content\deployment.json" "test.raptor.iotnxt.io"

Sample Output

Secured package file written to the following path: C:\Demo\IoTnxt.Raptor.Device.Teltonika.v.4.0.21.1-rc\Content\deployment.secured.json

Additional to the digital signature which is applied to the file, it also contains a specific message structure to ensure that the deployment agent van verify the digital signature.

Verify - Verifying package digital signature.

Verifying the file content is a simple process where specify the file to verified and the associated certificate subject name. Verification uses the certificate’s public key to execute verification.

Execute

raptorpm packagemanager verify -h

Output

verify:
  Verify the signed package by X509 certificate subject name.

Usage:
  raptorpm packagemanager verify [options] <Input> <SubjectName>

Arguments:
  <Input>          Argument to specify a input file path of the package to be verified.
  <SubjectName>    Argument to specify the input file path of the package to be verified.

Options:
  Verbose, -v       Option to specify if command should be logged in detail
  -?, -h, --help    Show help and usage information

Sample Execute

raptorpm packagemanager verify "C:\Demo\IoTnxt.Raptor.Device.Teltonika.v.4.0.21.1-rc\Content\deployment.secured.json" "test.raptor.iotnxt.io"

Sample Output

Verification passed successfully.

Compile - Compile package info and deployment files into a Nuget package.

Compiling a driver’s configuration and deployment information follows the following standard to ensure that the driver can be deployed successfully.

Execute

raptorpm packagemanager compile -h

Output

compile:
  Compile a distribution package by author profile id

Usage:
  raptorpm packagemanager compile [options] <Input> <ProfileName>

Arguments:
  <Input>          Option to specify a input file path of the package to created or packaged.
  <ProfileName>    Specify the author profile id to use during package construct.

Options:
  Output, -o <o>                         Specify the output directory [default: ]
  Description, -d <d>                    Specify package description [default: ]
  DistributionPackageType, -t <NuGet>    Specify the package type as the destination output [default: NuGet]
  Verbose, -v                            Option to specify if command should be logged in detail
  -?, -h, --help                         Show help and usage information

Using the example, lets execute the following:

Sample Execute

raptorpm packagemanager compile "IoTnxt.Raptor.Device.Teltonika.v.4.0.21.1-rc" "ProfileA"

Output

Package created successfully

The compile command will produce the following two packages:

  1. IoTnxt.Raptor.Device.Teltonika.UI.4.0.21.1-rc.nupkg
  2. IoTnxt.Raptor.Device.Teltonika.UI.Meta.4.0.21.1-rc.nupkg

Distribute - Distribute, upload, the NuGet package to the device store.

The distribute command take care of uploaded the compile NuGet packages to the relevant device store, or NuGet repository , based on the configured distribution profile.

Execute

raptorpm packagemanager distribute -h

Ouput

distribute:
  Command to distribute package by device store profile

Usage:
  raptorpm packagemanager distribute [options] <Input> <ProfileName> <DeviceStoreName>

Arguments:
  <Input>              Option to specify a input file path of the package to distribute.
  <ProfileName>        Specify the profile name to use during package construct.
  <DeviceStoreName>    Option to specify the device store name to upload to.

Options:
  DeviceStoreSecurityProfile, -s <DeviceStoreSecurityProfile>    ]
                                                                 Option to specify the device store security profile name to use during upload. [default:
  Verbose, -v                                                    Option to specify if command should be logged in detail
  -?, -h, --help                                                 Show help and usage information

Sample Execute

raptorpm packagemanager distribute IoTnxt.Raptor.Device.Teltonika.UI.4.0.21.1-rc.nupkg "ProfileA" "Development.Store"

Sample Output

Package distributed successfully

Consolidate command to Sign; Compile and Distribute packages

A consolidate command has been added to assist the signing; packaging and distribution of drivers. This command will sign the deployment and package files, compile the driver and distribute based on the parameters provided.

The command also an argument to ignore already signed files, and skip the signing process if required. This can be achieved by using the -e false flag. Thus no exception when a file is already signed.

Lastly we also have the ignore duplicate flag available, -i true which will continue or not throw an exception if a driver has already been distribute to the specific store. In other words if we distribute driver X to store Y and driver X exist with the same version, the distribution process will not throw an exception. Thus ignoring the duplicate.

Execute

raptorpm packagemanager signcdistribute -h

Ouput

signcdistribute:
  Sign, compile and distribute driver UI and Meta package

Usage:
  raptorpm packagemanager signcdistribute [options] <Input> <ProfileName> <DeviceStoreName> <DeviceStoreSecurityProfile>

Arguments:
  <Input>                         Option to specify a input file path of the package to distribute.
  <ProfileName>                   Specify the profile name to use during package construct.
  <DeviceStoreName>               Option to specify the device store name to upload to.
  <DeviceStoreSecurityProfile>    Option to specify the device store security profile name to use during upload.

Options:
  ThrowExceptionOnAlreadySigned, -e          Throw an exception when a file is already signed and stop process, or specify false to continue [default:
                                             True]
  IgnoreDuplicates, -i <IgnoreDuplicates>    Option to specify if the process should ignore duplicates at destination use during upload. [default: True]
  Verbose, -v                                Option to specify if command should be logged in detail
  -?, -h, --help                             Show help and usage information

Sample Execute

raptorpm packagemanager signcdistribute IoTnxt.Raptor.Device.Teltonika.v.4.0.21.1-rc "ProfileA" "Development.Store" "Security.ProfileA"

Sample Output

[RaptorEnvironmentExtension.ConfigureServices] Injecting IRaptorEnvironment
Validation Options and arguments
Validation Options and arguments : Passed
Signing of files for package content
Expected files to sign:
Meta: IoTnxt.Raptor.Device.Teltonika.v.4.0.21.1-rc\Content\deployment.json
UI: IoTnxt.Raptor.Device.Teltonika.v.4.0.21.1-rc\Data\PackageInfo.json
Signing of files for package content: Passed
Compiling Packages
Compiling Packages: Passed
Distribute Meta Package
Distribute UI Package
Distribute Packages: Passed

Continue reading

Community

Home Documentation Third Party Software Licenses

Questions

About Us Contact Us FAQs

Website

IoT.nxt