CORE Appliance Commands

ucl register

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

• Generates a CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate request specifying the following:
  • SANSubject Alternative Names - Certificate field with a list of IP addresses. - the client appliance's known hostnames and IP addresses.
  • OU - the required partition name.
• Receives the signed certificate in the <partition-name>.pfx file and the latest version of the server-ca.p7b file.
• Encrypts the content of the <partition-name>.pfx using the appliance-specific passphrase.
• Stores the received files in the client's Certificates Folder.
  

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

• Issue: locked template.
  Registration of an ephemeral client using a wrong ACActivation Code increments the "ACActivation Code error" counter associated with the template. Once the limit is reached, the template becomes locked. Default: 5 errors.
• To unlock the template and reset its error counter, run ucl client refresh in the CLICommand Line Interface or use Clients Tab in the UI.
  
• To change the limit - modify the client-limit setting in Partition Settings

ucl unregister

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

Preconditions:

1. In the CORE database:

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.

2. In the appliance's file system:

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:

• By default, it creates the server-ca.p7b file using binary DERBinary file, serialized ASN.1 structure encoding in the CORE Client Certificates Folder.
• The filename extension of the explicitly specified -o <filepath> impacts the file encoding as follows: 
  • filename extension .pem - encodes the file in PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" format.
  • any other extension - encodes the file in binary DERBinary file, serialized ASN.1 structure encoding.

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:

• Applies to client certificate obtained using CORE Appliance Commands.
• Renews the partition's certificate for the period specified by the system settings (default: 3 yearsFor any time interval setting in years, 1 year is converted to 365 days).
• Refreshes the server-ca.p7b file in the client's Certificates Folder.

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 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 KMIPKey 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 KMIPKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server.

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:

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:

  • The appliance is no longer listed as the partition's client

  Error (ucl): Login failed
  
  Additional error information:
  
  Client <client name> is missing, code=3, partition=<partition name>
  
  

  To resolve the issue, ask the partition's SOSecurity officer - UKC partition administrator role. to reregister your appliance.

  • Client's SSLSecure Sockets Layer - a cryptographic protocol that provides communications security over a computer network. certificate's trust issue:

  Error (ucl): Login failed
  
  Additional error information:
  
  Server's group is offline
  
  CURL error code=60, http-code=-52295041: SSL certificate problem: unable to get local issuer certificate

  In this case ( unable to get local issuer certificate),  the root cause is the missing or expired trust certificate. Rerun the ucl root_ca command.

  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 EKMEnterprise Key Management - previous name of the product. Service stop in the EP server. Ask your root SOSecurity 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 SOSecurity officer - UKC partition administrator role. to perform the ucl system-settings get command and resolve the issue.

ucl version

This command displays the UCLUnbound Command Language client software version.