CLI

The CORE command-line interface (CLICommand Line Interface) applies to appliances that installed the CORE server or client software. To invoke CORE CLICommand Line Interface command, enter ucl (Unbound Command Language) with the appropriate parameters in your platform's CLICommand 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:

• Management commands

CORE management:

• Root SO Commands
• Partition SO Commands
• Key Management Commands

Client management:

• CORE Appliance Commands
• Crypto Operation commands
• Signing Commands
• Certificate Commands
  

As a rule, UCLUnbound Command Language commands may be used on all OS platforms. Nevertheless, the following commands are available on the specific platforms only:

Command	Windows	Linux	MacOS
ucl sync-cert (Windows) and ucl sync-cert (MacOS)	√		√
ucl import-store (Windows)	√
ucl sign-code	√
ucl verify-code - Windows	√
ucl sign-rpm		√
Export to PGP Keyring		√	√

UCL Command Overview

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

• Processed by the platform's command shell.
• UCLUnbound Command Language does not provide a login session. Therefore, each command must carry the specification of the targeted CORE partition and the partition-specific user's credentials or access token exchanged for the user's credentials. Refer to UCL Command Authorization.
• UCLUnbound Command Language command is processed by one of the CORE servers specified in the client's Servers Setting.

Structure of UCL Commands

The UCLUnbound 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.

• A user credentials must be provided as follows:
  • CORE and LDAPLightweight Directory Access Protocol-based authentication -

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

  Refer to Authentication with Credentials
  

  • OpenID-based authentication:

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

  Refer to Authentication with Token

Authentication Options

Authentication with Credentials

For authentication with CORE or LDAPLightweight 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:
  • The default USER for the key-management commands.
  • The default SOSecurity officer - UKC partition administrator role. in all other cases.
• 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 SOSecurity officer - UKC partition administrator role. when it operates in an inherited partition (Part-inherit). In such a case, you must use Root SOSecurity 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 JWTJSON 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 SOSecurity 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 UCLUnbound 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 UCLUnbound Command Language command requires:

AuthenticationProcess 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

UCLUnbound 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:
  • Configure its embedded client. See Client Appliance Settings Summary.
  • Register its embedded client with the required partitions. For example, the Root partition. See Registered Clients .

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 UCLUnbound 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.