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 CSR
Certificate 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:
- SAN
Subject Alternative Names - Certificate field with a list of IP addresses. - the client appliance's known hostnames and IP addresses.
- OU - the required partition name.
- SAN
- Receives the signed certificate in the
<partition-name>.pfx
file and the latest version of theserver-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
- Ephemeral client registration
Example:
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 "AC
Activation 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 CLI
Command 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:
- In the CORE database:
- In the appliance's file system:
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.
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 DER
Binary file, serialized ASN.1 structure encoding.
- filename extension
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 years
For 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 KMIP
Key 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
- Client's SSL
Secure Sockets Layer - a cryptographic protocol that provides communications security over a computer network. certificate's trust issue:
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 SO
Security officer - UKC partition administrator role. to reregister your appliance.
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 certificateIn this case (
unable to get local issuer certificate
), the root cause is the missing or expired trust certificate. Rerun the ucl root_ca command.- 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
- Access is forbidden
- Service unavailable
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 SO
Security officer - UKC partition administrator role. to perform the ucl system-settings get command and resolve the issue.
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.
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.