CORE Appliance Commands

ucl register

The ucl register command finalizes the appliance's registration process as the CORE client. It performs the following:

Registration variants:

  • Standard client registration
  • ucl register -n <client name as used in the “ucl client create” command> -p <partition name> -c <Activation Code>

    Example:

    ucl register --name client1 -p CodeSign1 -c 170355
  • Ephemeral client registration
  • ucl register [-n <client name >] // Default: hostname -p <partition name> -t <name of template in the partition> -c <Activation Code>

    Example:

    ucl register --name M1 -t Master -p CodeSign1 -c 170355392745

Troubleshooting

ucl unregister

This command removes the specified partition's certificate from the client appliance.

Preconditions:

  1. In the CORE database:
  2. The client's name must not appear in the partition's client list. Before using this command, delete the client from the partition's client list: ucl client delete.

  3. In the appliance's file system:
  4. The partition's certificate must be valid. If the certificate is expired, this command fails with the following Error: Failed to parse <partition-name>.pfx. In such a case, delete the <partition-name>.pfx file from the Certificates Folder.

ucl unregister -p <partition name>

Note
The client's name is not required. The system retrieves it from the partition's certificate.

Example:

ucl unregister -p CodeSign1

Note
In an unlikely event of deleting the last partition client, use Recovery of Partition's Certificate to create the first client.

ucl root_ca

This command downloads the CORE Root CA repository file.

ucl root_ca
[-o <filepath>]

Output options:

For example, file generated by

ucl root_ca -o ./root_ca.pem

begins with the following line:

cat ./root_ca.pem
-----BEGIN CERTIFICATE-----

ucl renew

The command:

Note
To renew a CORE server certificate, use ekm_renew_server_certificate.

ucl renew -p <partition name>

Examples:

  • Renew a standard partition certificate:
  • ucl renew -p test1

    Client certificate renewed up to 12-Sep-2021

  • Renew the root partition certificate:
  • ucl renew -p root --user so

    so@root's password: **********
    Client certificate renewed up to 12-Sep-2021

ucl whoami

This command displays the caller's client name in each registered partition (by default) or the specified partition.

ucl whoami [-p <partition> ] // the partition name [-v | -verbose] // provide additional information

ucl diagnose

This command:

  • Assesses the following prerequisites for running CORE commands:
    • Client configuration. At least one server listed in the Servers Setting. is ready to process CORE client requests.
    • Partition configuration. The client appliance is listed among the specified partition's clients.
    • Certificates. The certificates (client and trust) are valid.
    • Credentials. The specified or implicit user's credentials are valid.
    • Software release. The client's software release is compatible with the server's software release.
  • Outlines operation permitted to the user by:
    • Presenting the user's Role - see Roles.
    • Listing operations permitted to the user.

Note
Only the KMIPClosedKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server-compliant operations are presented using the KMIP Usage Guide Version 1.4 terms. In particular, Enable/Disable operations are always missing from this list because these operations are extensions to KMIPClosedKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server.

ucl diagnose -p <partition> // the partition name [-a | --all] // test all server[:<port>]s in the client's conf

The configured EP servers that cannot be reached are reported. For the other EP servers, the sequence of tests is either completed or stopped if an error occurs:

ep1 : Successfully logged in : YES User using default password : YES The appliance is registered with a single partition : YES Partner is reachable : NO Error (pkcs#11) 0x00000030: EKM error Additional error information: Server's group is offline CURL error code=0, http-code=503: CURL error code=0, http-code=503:

Troubleshooting

The ucl diagnose command performs the predefined sequence of tests. Failure to perform one of the tests stops the procedure and displays the relevant error message.

This section presents common error cases, the corresponding error message(s), and specifies the recovery steps.

Note
To obtain additional error information, use the --verbose (-v) option in the command. This option presents up to two additional error cause layers:
1. Additional error information.
2. CURL error (optional) - is presented to pinpoint the root cause.

  • Error (ucl): No partition found – the partition's certificate is missing. Check the PKI Trust Repository. As needed, reregister the client.
  • Error (ucl): Login failed. If the cause is not obvious, rerun the command with the --verbose option.

    Here is a sample of the common Login failed causes that are not related to the user's credentials:

    TBD - move to Maintenance
    • EP address issue
    • Error (ucl): Login failed

      Additional error information:

      Server's group is offline

      CURL error code=6, http-code=-1267356241: Couldn't resolve host 'e21'

      In this case ( Couldn't resolve host 'e21'),  the root cause is a failure to DNS-resolve the EP name (e21) listed in the client configuration. To update the configuration, edit the Client Configuration.

    • EP port or service issue
    • Error (ucl): Login failed

      Additional error information:

      Server's group is offline

      CURL error code=7, http-code=161438367: Failed to connect to ep1 port 1443: Connection refused

      In this case ( Failed to connect to ep1 port 7443: Connection refused),  the root cause is a failure to connect to the specified EP server's port. To update the configuration, edit the Client Configuration.

      If the port is a valid one, the possible cause of the error is the EKMClosedEnterprise Key Management - previous name of the product. Service stop in the EP server. Ask your root SOClosedSecurity officer - UKC partition administrator role. to perform the ucl system-settings get command and resolve the issue.

    • Access is forbidden
    • Error (ucl): Login failed

      Additional error information:

      Server's group is offline

      CURL error code=0, http-code=403

      In this case ( http-code=403),  the root cause is an attempt to connect to a non-EP server in the CORE cluster. For example, the Client Configuration specifies a Partner server as its entry point. Examine and change the configuration.

    • Service unavailable
    • Error (ucl): Login failed

      Additional error information:

      Server's group is offline

      CURL error code=0, http-code=503:

      CURL error code=0, http-code=503:

      In this case ( http-code=503),  the possible cause of the error is an issue with the Partner server. Ask your root SOClosedSecurity officer - UKC partition administrator role. to perform the ucl system-settings get command and resolve the issue.

ucl version

This command displays the UCLClosedUnbound Command Language client software version.

ucl version