CORE Client

By default, each device used to access a CORE partition must have a certificate issued for the device and authorizing its access to the specified partition. In addition, the COREpartition hierarchy feature enables a device to obtain the certificate of a parent partition and use it to access descending partitions. See One Certificate - Many Partitions.

This topic specifies different options to create a CORE client.

Client Types and Certificates

The CORE client certificate is used to validate the identity of its holder and authorize access to the partition listed in the certificate.

CORE client certificates are required by applications running in different setup and regulatory environments: manual or automated deployment, using certificates signed by the CORE CA or an external CA, integrated with the CORE client stack or bypassing CORE client-side processing, serving a single client or group of clients. For each environment CORE provides the dedicated method to obtain client certificate resulting in the following classification of CORE clients:

Registered client
Serves applications that use the CORE Client Stack while requiring individual setup on both the server and the device sides.
Ephemeral client
Serves applications that use the CORE Client Stack in automated, cloud-native, and Docker environments. Unlike the case of the registered client, many ephemeral clients may be created using a one-time setup on the server-side.
Full client
Serves applications that interface CORE using interop protocols and standards such as KMIPClosedKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server and RESTClosedRepresentational State Transfer (REST) - an architectural style that defines a set of constraints and properties based on HTTP. Web Services that conform to the REST architectural style, or RESTful web services, provide interoperability between computer systems on the Internet. API or other methods that bypass client-side processing offered by the CORE client stack. The one-time setup of such a client in the CORE system may apply to one device or a range of devices.

Note
Certificates of the above clients are signed by the CORE Root CA of the system.

External client
Similar to the Full client while addressing the following client-side requirement:  the certificate must be signed by an external CA.

A quick comparison of client types:

Full vs External
An external client can not access EP port 443 that validates certificates signed by the CORE CA only.
Full vs Ephemeral
A group of full-client devices will be using the same certificate and will appear under the same client name.
A group of ephemeral-client devices will be using discrete certificates and will appear under distinctive client names.

    Comparing FULL and Ephemeral clients

Registered Clients

A registered client is created by specifying the client creation mode=ACTIVATE.

Quickstart

In the following example, we create a CORE client and install its certificate on a device that issues the registration request. We assume the following:

Step Run on Command
1 EP

Create client "my-pc" in partition "test"

ucl client create -m ACTIVATE -n my-pc -p test -w Password2!

This command returns Activation Code (ACClosedActivation Code)

2 Device

Exchange ACClosedActivation Code for the certificate

ucl register -n my-pc -p test -c <AC>

The certificate file (<test.pfx>) is stored in the CORE Client Certificates Folder. It is secured by the device's unique passphrase.

3 Device

Test

ucl partition list

Details

  1. The ucl client create -m ACTIVATE (or the corresponding UI command provides the following options:
    1. It allows specifying the validity period of the Activation Code. If omitted, the client-timeout in the Partition Settings Summary is used. Its default is 20 minutes.
    2. Allows specifying the validity period of the certificate that will be obtained using the Activation Code. If omitted, the certificate is valid for CORE system-specific period defined by client-exp in Certificate Validity Settings. Default: 3 yearsClosedFor any time interval setting in years, 1 year is converted to 365 days.
    3. Allows specifying the number of digits in ACClosedActivation Code, Default: 6 digits.
    4. Allows specifying IP-based restrictions in obtaining the certificate.
  2. For the complete list of parameters, see ucl client create -m ACTIVATE.

  3. The ucl register command:

    1. Creates CSRClosedCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate with all known to the device hostnames and IPs in its SANClosedSubject Alternative Names - Certificate field with a list of IP addresses. field and the given partition's name in the subject's OU field.
    2. The EP server validates the request, signs the certificate using the CORE Root CA key, and returns it to the client.
    3. CORE client secures the certificate file using a passphrase that is unique to the device. The certificate can be used on this device only.

    For the complete list of parameters, see the ucl register command.

  4. The secured certificate file (<partition-name.pfx>) is stored in the CORE Client Certificates Folder.
  5. Note
    In addition, the ucl register command pulls from EP the CORE Root CA certificate. It will be used by the client to validate the certificate presented by EP during their mutual SSLClosedSecure Sockets Layer - a cryptographic protocol that provides communications security over a computer network. authentication.

Client Management in Partition

Management of CORE client in a partition focuses on matters related to its certificate.

Note
The device-specific CORE client settings are managed on the device.

  • Update. See Client Settings Update.
  • Delete. A partition SOClosedSecurity officer - UKC partition administrator role. can delete the partition's client from its database. Such a client is no longer authenticated as the CORE client.
  • Unregister. To erase the certificate of a deleted client from a device that has the certificate, run the ucl unregister command from the device.
  • Renew. To renew a registered client's certificate, run the ucl renew from the device.
  • Note: This command applies to the registered clients only.

  • Implicit registration. The ucl partition create command automatically registers the executing device as a client of the created partition. The client's name is the hostname of the device.
  • Implicit registration. The ucl partition create command automatically registers the executing device as a client of the created partition. The client's name is the hostname of the device.
  • Note:
    The corresponding partition-create command on UI creates the Full Client certificate.

Ephemeral Clients

In the preparation for the creation of ephemeral clients, we create a template client by specifying the client creation mode=TEMPLATE. This command generates an activation code that may be reused by many devices. The code is valid for the specified period that can be renewed as needed.

Ephemeral clients are identical to the registered clients, yet:

  • They are created and registered by a single ucl register command that reuses the same set of parameters by all devices that register using this method. In particular, the device's hostname automatically becomes the client's name.
  • The validity period of their certificates is specified by their template's setting.
  • To renew the certificate of an ephemeral client, unregister the client and reregister it using the same command as long as the activation code remains valid.

Note
Unlike the other types of clients, ephemeral clients may be not stored in the CORE dtabase. This feature is specified in template settings and applies to all clients.

Quickstart

In the following example, we create a CORE client on many devices. We assume the following:

Step Run on Command
1 EP

Create template "my-template" in partition "test"

ucl client create -m TEMPLATE -n my-template -p test -w Password2!

The command returns an Activation Code (ACClosedActivation Code)

2.1 Device-1

Exchange the ACClosedActivation Code for the Device-1 certificate

ucl register -t my-template -p test -c <AC>

By default, the client name is the hostname of the device.

The certificate file (<test.pfx>) is stored in the CORE Client Certificates Folder. It is secured by the device-unique passphrase.

2.2 Device-2

Exchange ACClosedActivation Code for the Device-2 certificate

ucl register -t my-template -p test -c <AC>

By default, the client name is the hostname of the device.

The certificate file (<test.pfx>) is stored in the CORE Client Certificates Folder. It is secured by the device-unique passphrase.

2.n Device-N

Exchange ACClosedActivation Code for the Device-N certificate

ucl register -t my-template -p test -c <AC>

By default, the client name is the hostname of the device.

The certificate file (<test.pfx>) is stored in the CORE Client Certificates Folder. It is secured by the device-specific passphrase.

Details

  1. The ucl client create -m Template or the corresponding UI command provides the following options:

    1. It allows specifying the validity period of the Activation Code. Default: 20 minutes.
    2. Allows specifying the validity period of the certificate that will be obtained using the Activation Code. Default: 30 minutes.
    3. Allows specifying the number of digits in ACClosedActivation Code. Default:16 digits
    4. Allows specifying IP-based restrictions in obtaining the certificate.
  2. For the complete list of parameters, see ucl client create -m Template. To create an ACClosedActivation Code that is valid for 10 minutes, yet its user obtains a certificate valid for 12 hours, create the following template

    ucl client create -p test -m Template -n my-template --ac_validity 10 --cert_validity 720 -w *******

  3. The ucl register -t command

    1. Enlists the client's name in the partition. Default: hostname of the device.
    2. Obtains, secures, and stores the client's and the Root CA certificate as the ucl register command.

    For the complete list of parameters, see the ucl register command. Example:

    $ hostname

    ip-192-168-0-182.dyadicsec.local

    ucl register -t my-template -p test -c <AC>

    Registration of ip-192-168-0-182.dyadicsec.local completed successfully

    The new client name is ip-192-168-0-182.dyadicsec.local.

Note
Once an ephemeral client's certificate expires, the client is automatically deleted from the partition's database when a new ephemeral client is added to the partition.

Template Management Notes

To manage a template of ephemeral clients, use the standard client management commands. Among all clients of a partition they are identified by distinctive "activation Type": "Template Client".

Full Client

A full client is created by specifying mode=FULL.

The Full client creation is used in the cases when the CORE client certificate is required, but CORE client software is not applicable in the specific application. In particular, this applies to CORE RESTClosedRepresentational State Transfer (REST) - an architectural style that defines a set of constraints and properties based on HTTP. Web Services that conform to the REST architectural style, or RESTful web services, provide interoperability between computer systems on the Internet. API applications, CORE ClientlessClosedSystem that is using Unbound Java Security Provider without dependency on the UKC Client software. Java applications, and to KMIPClosedKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server clients that are served by CORE .

Full clients are similar to the registered clients, yet their certificates are:

  • Fully created and signed by CORE Root CA.
  • May be used by any device or restricted to the devices specified in its SANClosedSubject Alternative Names - Certificate field with a list of IP addresses. list.
  • Must be delivered to the designated device and installed as specified by applications that use them.
  • Secured by a passphrase that is protected by an application that uses the certificate.
  • To renew the certificate, use the Certificate Renew and redistribute the renewed certificate to the relevant devices.

Quickstart

In the following example, we create a CORE client and its certificate that may be used by any device. We assume the following:

Step Run on Command
1 EP

Create full-client "my-rest-client"

ucl client create -m FULL -n my-rest-client -p test \
-o ./my-rest-cert.pfx --pfx_password <pfx passphrase> -w Password2!

2 Device

Install the certificate as required by the application that will use it.

Details

Note
For devices that use the CORE Client Stack, we recommend creating clients using registered or ephemeral clients. Nonetheless, to create a full certificate for a device that uses the CORE Client Stack, see ucl client create -m FULL for CORE client. In such a case, the generated certificate must be installed in CORE Client Certificates Folder on the client's device.

External Client

To create a CORE client using the certificate of device that has been signed by non-CORE CA, use mode=EXTERNAL. Notable differences:

  • In the other methods, the client certificate was created on EP and distributed to the client. In this method, it is vice versa: the certificate is created by the client and forwarded to EP.
  • Clients with externally signed certificates are served by EP on a different TCP/IP port. Once the port is determined, EP configuration is extended to include the selected port.

Quickstart

In the following example, we create a CORE client using the device's certificate. We assume the following:

Step Run on Command
1 EP

Create externally certified client using my-external.cer

ucl client create -m EXTERNAL -n my-pc -p test -c my-external.cer

2 EP

Add "my-ca.cer" to the trust store used by EP to validate the client's certificate.

see Client Certificate Issued by External CA.

3 Device Use the application-specific method to test the certificate.

External Client Cert Details

Prerequisites. To be accepted by CORE , the device's certificate:

External Client Management Notes

Create

One Certificate - Many Partitions

This feature enables a device that holds the CORE certificate of a particular partition to gain access to its all "subtended" partitions.

In particular, this feature allows a client that holds the Root partition certificate to use it in accessing all partitions that are hierarchically linked to the Root partition. The linkage is controlled bottom-up by a partition's SOClosedSecurity officer - UKC partition administrator role. who declares or revokes the Root partition as its parent partition. See Cert-propagation.

Note
To become a client of the Root partition, use any method listed in this section. In this case, the Root SOClosedSecurity officer - UKC partition administrator role. acts as an SOClosedSecurity officer - UKC partition administrator role. of the Root partition.

Certificate Misuse Prevention

Certificate misuse prevention addresses scenarios where a compromised CORE client certificate is reused from a device it was not intended to.

  • For registered and ephemeral clients, the prevention is assured by locking the certificate to the device that issued the ucl register command.
  • For full and external clients, the certificate is not generated on the device itself. Therefore it is no locked to the device and its passphrase is protected by an application that uses the certificate. Such a certificate can be compromised and reused on an unintended device.

To prevent certificate misuse, CORE client settings allow enforcing validation of certificate ownership by EP. The validation compares the IP address of the device IP with the addresses that are permitted to use the certificate. The permitted IP addresses may be:

Validation of Device IP

To enforce validation of the device IP, enable the client's check-ip setting.

The check-ip setting is specified per partition (for all clients) and, as needed, per individual client. By default, it applies to all clients of a partition except the clients that explicitly specified their decision. See Check-IP and Allow-NAT.

Note
The default check-ip setting of a partition doesn't enforce IP validation.

Quickstart

In this quickstart, we enforce certificate validations on all clients of partition "test" except client1. Then we add a new FULL client2 and restrict its access to a range to a range of IPs. Note that since its check-ip setting is undefined, the partition's check-ip setting applies to this client.

We assume that the partition's SOClosedSecurity officer - UKC partition administrator role. password is Password2!

  1. Enforce certificate validation on all clients of the partition that keep their check-ip undefined.
  2. ucl settings set -p test -k check_ip -v 1 -w Password2!

  3. Make sure that client1 is exempted from its certificate validation
  4. ucl client update -p test -n client1 -k check_ip -v 0 -w Password2!

  5. Create a new FULL client2 and restrict its certificate use to the IPs in the following range: from 192.168.0.97 to 192.168.0.126 (using CIDRClosedClassless Inter-Domain Routing, an IP addressing notation notation):
  6. ucl client create -m FULL -n client2 -p test \
    -k ip_range -v 192.168.0.96/27 \
    -o ./my-test.pfx --pfx_password ********* -w Password2!

Validation of Device IP under NAT Conditions

In some client-server topologies, the source IP address of a packet arriving at the server may be changed on its route to the server. To eliminate a false positive detection in such networks, the device IP address is carried in the packet's payload.

The allow-nat setting directs the CORE client software to add its IP to the packet and directs the validation process to use the IP detected by the device vs. the IP detected by the server.

Similarly to the check-ip, the allow-nat setting is specified per partition and client. By default, it applies to all clients of a partition except the clients that had chosen to enforce their own decision. See Check-IP and Allow-NAT.

Quickstart

Let's assume that in the previous example, the network connection between the client2 device and EP doesn't preserve the original IP address of the device. In such a case, the #3 command will be updated to specify the allow-nat option:

ucl client create -m FULL -n client2 -p test \
-k check-ip -v 1 \
-k allow-nat -v 1 \
-k ip-range -v 192.168.0.96/27 \
-o ./my-test.pfx --pfx_password ********* -w Password2!

Now, all devices with their host IP address in the 192.168.0.96/27 range may use the my-test.pfx certificate to access the test partition.

Specification of Valid IPs

IPs of devices that are permitted to use client certificate are specified

Appendix: Client Settings

Most of the client settings are fixed during the client creation. You may modify the following settings using the referred command

name
client's name.
template name
Applies to ephemeral clients only. Indicates the name of the template that was used to create the client.
partition
name of the partition that hosts the client.
activation type
  • Activation Code - created using ACClosedActivation Code.
  • Certificate Download - created using a FULL certificate.
  • Certificate Request - created implicitly while creating a new partition using the ucl partition create command.
  • Ephemeral - created using an ACClosedActivation Code that is associated with the template specified in the client template field.
  • Template Client indicates that it is a template for creating ephemeral clients.
  • External Client - created using a certificate signed by an external CA.
activation status
PENDING - indicates that the ACClosedActivation Code code may be used. ACTIVATED - indicates the ACClosedActivation Code code has been already used.
activation locked
YES indicates that the number of attempts to use the wrong ACClosedActivation Code exceeded the number specified in the partition settings. To unlock the client, see ucl client refresh.
Created at
Date of creation.
Last Updated at
Date of the last update.
Certificate validity
Total validity period assigned to the certificate.
Certificate expires on
Date of expiration.
Certificate is expiring
TRUE indicates that the certificate is approaching its end of validity. This status flag is turned on several days before the certificate's expiry. See the system's Certificate Validity Settings.
Certificate renew required
TRUE - the certificate has expired.
check-ip
0 (NO) - Do not validate the certificate owner's IP.
1 (YES) - Validate the certificate owner's IP.
Default: follow the partition's setting.
allow-nat
This setting is applicable if it is required to validate the certificate owner's IP. 
0 (NO) - Use the received Source IP from the IP header.
1- (YES) - Use IP value carried in the message payload.
Default: follow the partition's setting.
ip-range
This setting is applicable if it is required to validate the certificate owner's IP. 
Specifies the range of IP that can use client-certificate. Uses CIDRClosedClassless Inter-Domain Routing, an IP addressing notation format. For example:
192.168.0.96/27 identifies (32 - 2) IPs: from 192.168.0.97 to 192.168.0.126
Default - all IPs (0.0.0.0/0).

Note
For the description of the check-ip, allow-nat, and ip-range, see Certificate Misuse Prevention.