SoftSIM CLI

Fetch, decrypt, and decode SoftSIM profiles seamlessly.

The SoftSIM CLI is a tool that helps out with provisioning before and during flashing of your SoftSIM enabled device. The tool aimed at usage in production, i.e. when manufacturing devices, but can also be used in other settings. The source code is available here.

Requirements

Before you can use this tool you will have to have an account with some SoftSIMs as well as a SoftSIM API key.

A SoftSIM API key is different from a normal API key and can only fetch SoftSIM profiles, i.e. it cannot perform other actions that a normal API key can.

To obtain a SoftSIM API key you will need a key pair. We recommend using 4096 bit keys.

To generate a key pair run the following command in your terminal:

$ ssh-keygen -t rsa -m PEM -b 4096 -f <path_to_new_key>

The public key is expected to be PEM encoded:

-----BEGIN PUBLIC KEY-----
.....
-----END PUBLIC KEY-----

This can be obtained by running:

$ ssh-keygen -e -m PKCS8 -f <path_to_public_key>.pub

Use the to public key to create an API key on https://app.onomondo.com/api-keys/softsim/new

Installation

Head over to https://github.com/onomondo/onomondo-softsim-cli/releases and grab the latest release for your platform. Currently, we only have releases being compiled to x86 for macOS, Windows, and Linux—it is however possible to compile to another instruction set from the source code, familiarity with Cargo can help in this endeavor.

Usage

Usage: softsim [OPTIONS] <COMMAND>

Commands:
  fetch
          Fetch profiles from API
  next
          Find next available profile. Decrypt and decode the profile and mark it as used
  help
          Print this message or the help of the given subcommand(s)

Options:
  -v, --verbosity...
          Verbosity level
  -h, --help
          Print help
  -V, --version
          Print version

Provisioning is split in two distinct steps:

1. Pre-production: Fetch n profiles from the Onomondo API to avoid excessive load on API and to remove any dependencies on stable internet. The profiles are encrypted using your public key.

2. During production: Continuously get a new unique profile correctly formatted to specifications.

These steps correspond one-to-one with the available commands in the CLI tool.

Fetch

This command fetches the specified number of profiles from the Onomondo API. Use the SoftSIM API generated in our platform to get access.

Pulls profiles from Onomondo's API and writes to disk. Specify count to fetch many for production usage. softsim breaks the count into batches of max. 1000.

Usage: softsim fetch [OPTIONS] --api-key <API_KEY>

Options:
  -a, --api-key <API_KEY>

  -n, --count <NUM_OF_PROFILES>
          [default: 1]
  -o, --out <OUTPUT>
          [default: profiles]
  -u, --url <url>
          [default: https://api.onomondo.com/sims/profiles]
  -h, --help
          Print help

Examples

Get 5678 profiles and store under ./profile/:

softsim fetch -a <your_api_key> -n 5678

Specify output path:

softsim fetch -a <your_api_key> -n 1000 -o "batch1"

Next

This command finds the next unused profile on your local system. The profile is decrypted using the private key pointed to by the --key argument. After decryption and encoding the file is prepended with __ to invalidate the profile. Specify format to change encoding.

HEX - suitable for SoftSIM integrations made by Onomondo

JSON - outputs RAW profile and relevant meta information.

Usage: softsim next [OPTIONS] --key <KEY>

Options:
  -k, --key <KEY>
          Path to private key
  -i, --in <SET_OF_PROFILES>
          Path to encrypted profiles [default: ./profiles]
      --format[=<FORMAT>]
          Output format [default: hex] [possible values: hex, json]
  -h, --help
          Print help

Examples

Write hex encoded profiles to stdout`. Optionally, this can be piped directly to a device, if it is ready to receive a profile.

--key should point to the private key generated in the previous steps.

softsim next --key <path_to_private_key>

Specify format to json

softsim next --key resources/test/key --format=json

softsim next can be called from manufacturing scripts as needed.