CLI

The CORE command-line interface (CLIClosedCommand Line Interface) applies to appliances that installed the CORE server or client software. To invoke CORE CLIClosedCommand Line Interface command, enter ucl (Unbound Command Language) with the appropriate parameters in your platform's CLIClosedCommand Line Interface interface.

By default, ucl is installed in the following folder:

  • On Windows: C:\Program Files\Dyadic\ekm\bin
  • On Linux and MacOS: /usr/bin

This section starts with UCL Command Overview. The rest of the section is divided into the following groups:

UCL Command Overview

Unbound Command Line (UCLClosedUnbound Command Language) is available on appliances that have installed the CORE client or server software. The UCLClosedUnbound Command Language commands are:

Structure of UCL Commands

The UCLClosedUnbound Command Language commands have the following structure:

    ucl <command> [options] \
    [<targeted partition>] \
    [<user credentials>]

  • The targeted partition is specified as follows:
  • -p [--partition ] < partition name>

    A reference to the targeted partition may be omitted in the following cases:

    • A command targets the root partition.
    • A command is executed by an appliance that has only one CORE partition' certificate.

Authentication Options

Authentication with Credentials

For authentication with CORE or LDAPClosedLightweight Directory Access Protocol credentials, use

--user <username> -w [--password ] <password>

If you provide partial credentials or omit the partition, the CORE client software acts as follows:

  • Username. If you omit the --user parameter, the system assumes the following username:
  • Password. If you omit the user's password when it is required, the system prompts for it using the following prompt: <username>@<partition name> password:

Note
A full username combines the user's and the partition's name using @-notation: <user name>@<partition name>. In general, using a short username is sufficient unless the user of partition A is allowed to operate in partition B.
In particular, this applies to the Root SOClosedSecurity officer - UKC partition administrator role. when it operates in an inherited partition (Part-inherit). In such a case, you must use Root SOClosedSecurity officer - UKC partition administrator role. full username so@root. For example:
ucl client list -p CodeSign --user so@root -w <so@root's password>

Authentication with Token

To authenticate a user with the CORE JWTClosedJSON Web Token - means of representing claims transferred between two parties token, use JSON format to specify the "token" :"value". Note that all quote (") characters must be escaped using the backslash (\):

-w {\"token\":\"<OpenID token-string>\"}

Note that the CORE token already contains:

  • Name of the partition.
  • Name of the user.
  • Validity period.
  • The IP address that is authorized to use the token.

Example:

The following token authorizes the user from IP172.31.0.238 to act as the "test" partition SOClosedSecurity officer - UKC partition administrator role. for 30 minutes. The token is issued by UNBOUND.

eyJraWQiOiIweDAwNTEyODk0MzQ2MTBhNGVhYyIsImFsZyI6IkVTMjU2In0. eyJwYXJ0aXRpb25zIjp7InRlc3QiOlsic28iXX0sInN1YiI6InNvQHRlc3Qi LCJvcmlnIjoiMTcyLjMxLjAuMjM4IiwiaXNzIjoiVU5CT1VORCIsImlzX3Jl ZnJlc2giOmZhbHNlLCJ1c2VfZXBoZW1lcmFsIjpmYWxzZSwiZXhwIjoxNjI5 MTM0MDEwLCJpYXQiOjE2MjkxMzIyMTAsImp0aSI6ImQwYzU2OWE3LWFhYTMt NGU3Yy04YTBjLTI2YTJlZDUzYjQwNyJ9.
PAgTUIzBGL9g2N25oqyiLu1beP0mbCjMO_ZIiHAiERYNTSvlFXaQlA60ReqkUTu55qloZAgVDD9twtP83pNd0A

Note: token has no line breaks. They were added for clarity.

It carries the following data:

{
"partitions": {
"test": ["so"]},
"sub": "so@test",
"orig": "172.31.0.238",

"iss": "UNBOUND",

"is_refresh": false,
"use_ephemeral": false,

"exp": 1629134010,

"iat": 1629132210,

"jti": "d0c569a7-aaa3-4e7c-8a0c-26a2ed53b407"

}

Example of use:

ucl sign-code --file C:\tmp\test.exe -n my-sign-key -w {\"token\":\"eyJraWQiOiIweDAwNTEyODk0MzQ2MTBhNGVhYyIsImFsZyI6IkVTMjU2In0. eyJwYXJ0aXRpb25zIjp7InRlc3QiOlsic28iXX0sInN1YiI6InNvQHRlc3Qi LCJvcmlnIjoiMTcyLjMxLjAuMjM4IiwiaXNzIjoiVU5CT1VORCIsImlzX3Jl ZnJlc2giOmZhbHNlLCJ1c2VfZXBoZW1lcmFsIjpmYWxzZSwiZXhwIjoxNjI5 MTM0MDEwLCJpYXQiOjE2MjkxMzIyMTAsImp0aSI6ImQwYzU2OWE3LWFhYTMt NGU3Yy04YTBjLTI2YTJlZDUzYjQwNyJ9.
PAgTUIzBGL9g2N25oqyiLu1beP0mbCjMO_ZIiHAiERYNTSvlFXaQlA60ReqkUTu55qloZAgVDD9twtP83pNd0A\"}

UCL Command Result

The result of the UCLClosedUnbound Command Language command appears in the following:

  • stdout:
    • Confirmation message or JSON-formatted info.
    • Error message.
  • stderr (use the echo $? command to show the result):
    • 0 value for success.
    • 1 (or any other non-zero value) for failure.

UCL Command Authorization

Execution of each UCLClosedUnbound Command Language command requires:

AuthenticationClosedProcess used to achieve sufficient confidence in the binding between the Entity and the presented Identity.:
1. Client Certificate that authenticates the device.
2. Credentials of the partition's user. Refer to Authentication Options.
 
Authorization:
1. Authorization to access the partition (its name is specified in the client's certificate).
2. Conformance with the Partition Key Policy.
3. Role (User Permissions) that permits such operation to the user.

Using UCL on Servers

UCLClosedUnbound Command Language commands on a CORE server are executed using the embedded CORE client software.

  • The main EP server:
    • Configures its embedded client during its bootstrap.
    • Has certificates of partitions that were by running the ucl partition create command on the server.
    • However, the main EP has no certificates of partitions created from other appliances or using UI. To access such a partition from the main EP, add it as the partition's client. See Registered Clients.
  • For all other CORE servers:

Using Special Characters

We use the term special characters to define ASCII printable characters (character code 32-127) that are neither letters nor digits. To use special characters in the UCLClosedUnbound Command Language commands, follow these rules:

  • Characters that have special meaning in the hosting OS shell must be escaped using the shell-specific escape character.
  • To use special characters in the CORE entity names (keys, partitions, clients, passwords), check the corresponding restrictions in Characters in CORE Names.