CLI
The CORE command-line interface (CLICommand Line Interface) applies to appliances that installed the CORE server or client software. To invoke CORE CLI
Command 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
- Crypto Operation commands
- Signing Commands
- Certificate Commands
CORE management:
Client management:
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 (UCL
is available on appliances that have installed the CORE client or server software. The UCLUnbound Command Language)
Unbound Command Language commands are:
- Processed by the platform's command shell.
- UCL
Unbound 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.
- UCL
Unbound 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:
- The targeted partition is specified as follows:
- A command targets the root partition.
- A command is executed by an appliance that has only one CORE partition' certificate.
ucl <command> [options] \
[<targeted partition>] \
[<user credentials>]
-p [--partition ] < partition name>
A reference to the targeted partition may be omitted in the following cases:
- A user credentials must be provided as follows:
- CORE and LDAP
Lightweight Directory Access Protocol-based authentication -
- OpenID-based authentication:
--user <username> -w [--password ] <password>
Refer to Authentication with Credentials
-w {\"token\":\"<OpenID token-string>\"}
Refer to Authentication with Token
- CORE and LDAP
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 SO
Security 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 SO
Security 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:
- Authentication
Process 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.