Client Management
A client represents a machine where a supported product such as ProtectFile, and CTE is installed. A client needs to be registered with the CipherTrust Manager to retrieve and store encryption keys to encrypt and decrypt data. When successfully registered, the client is automatically added to the CipherTrust Manager.
A client can be registered with the CipherTrust Manager by using a registration token generated on the CipherTrust Manager. This token is called the client registration token. The fingerprint of the server’s web interface certificate is also required for registering clients with the CipherTrust Manager.
The CipherTrust Manager provides options to manage registration tokens and clients.
Note
For client authentication to work in any domain, the issuer CA of that client certificate must be added in the domain and client_authentication
for that CA must be enabled. This is applicable only for the clients with authentication_mode
set as dn
.
Tokens
A token is a string that is used to register clients having ProtectFile, CTE, and CTE UserSpace installed with the CipherTrust Manager. The CipherTrust Manager provides options to create tokens, view existing tokens, view and modify their details, and delete them when they are no longer required.
The following table lists the parameters that are required when creating or managing a registration token on the CipherTrust Manager:
Parameter | Description |
---|---|
Certificate Authority ID | ID of the trusted CA that will be used to sign a client certificate during the registration process. By default, a local CA will be used to issue certificates. A signed Local CA certificate is used to secure communication between the CipherTrust Manager and clients. To use an external CA certificate, specify the ID of the Local CA signed by the external CA. |
Lifetime | Duration (in minutes, hours, or days) for which this token can be used for registering clients. Specify m for minutes, h for hours, and d for days. For example, specify the lifetime as:
By default, there is no time limit; the token can be used forever. |
Certificate Duration | Duration (in days) for which the CipherTrust Manager client certificate is valid. The default duration is 730 days. |
Maximum Clients | Maximum number of clients that can be registered using this registration token. By default, there is no limit; any number of clients can be registered using this token. |
Name Prefix | Prefix for the client name. This prefix will be used to construct names for clients whose names will not be specified during registration with the CipherTrust Manager using this token.
However, if a client's name is specified during registration, this name prefix will not be used for that client. |
Revocation Reason | Reason for revoking the client registration. |
Creating a Registration Token
A registration token can be created on the CipherTrust Manager. It is used when registering CipherTrust Manager clients with the CipherTrust Manager. A CipherTrust Manager administrator creates registration tokens.
To create a registration token:
Log on to the CipherTrust Manager GUI as administrator.
In the left pane, click Access Management > Registration Tokens.
On the right, click Add Registration Token. The Create New Registration Token wizard is displayed. This is a three-step wizard.
Click Begin to start token creation. The Configure Token screen is displayed.
(Optional) Specify a Name Prefix. Prefix for the client name. This prefix is used to construct names for clients whose names are not specified during registration with the CipherTrust Manager using this token.
If the name prefix is specified as
ks_client
, client names will be constructed asks_client#
; for example,ks_client1
,ks_client2
,ks_client3
, and so on.If the name prefix is not specified, the CipherTrust Manager will construct a random name for clients.
However, if a client's name is specified during registration, this name prefix will not be used for that client.
Specify Token lifetime. This is the duration (in minutes, hours, or days) for which this token can be used for registering clients. For example, specify the lifetime as:
1 minutes
for 1 minute2 hours
for 2 hours3 days
for 3 daysunlimited
for a token that never expires.
By default, the token lifetime is
unlimited
. The token will never expire.Specify Certificate Duration. This is the duration (in days) for which the CipherTrust Manager client certificate is valid. The default duration is
730
days.Specify Client Capacity. This is the maximum number of clients that can be registered using this registration token. The default capacity is
100
clients.Click Next. The Select CA screen is displayed.
On the Select CA screen, you can select a CA Type from the following:
Local - Select a Local CA from the given list available in the drop-down as per your requirement.
External - Select an External CA from the given list available in the drop-down as per your requirement.
Click Create Token. The Create Token screen is displayed. The created token is displayed on screen.
Click Copy next to the token. Save the copied token. This token will be used when migrating clients.
Click Done.
Note
While creating a registration token, the CA chain will be validated for the intermediate local CAs.
Getting the Fingerprint of the Server's "web" Interface Certificate
The fingerprint of the server's "web" interface certificate is unique. It is used when registering ProtectFile and CTE UserSpace clients with the CipherTrust Manager. A CipherTrust Manager administrator can provide you the fingerprint.
Fingerprint of the server’s web interface certificate can be viewed on the GUI or the API playground.
On the API Playground
To get the fingerprint:
Acquire an authorization token.
In the left pane of the API playground, click Client-Management/Tokens.
Under Client-Management/Tokens, click Web Certificate Fingerprint. The Web Certificate Fingerprint section of the API playground is displayed in the right pane.
Click GET. View the fingerprint details in the response output.
The SHA256 and SHA512 fingerprints of the server’s web interface certificate are displayed.
On the UI
To get the fingerprint:
Log on to the CipherTrust Manager as administrator.
In the left pane, click Access Management > Registration Tokens. The list of existing registration tokens with details such as their name, expiry, remaining usage count, and usage count is displayed.
On the right, under the CipherTrust ManagerWeb Server Certificate Fingerprint, the fingerprint is displayed.
The UI displays the SHA256 fingerprint. To get the SHA512 fingerprint, use the API playground.
Copy the fingerprint.
Save the fingerprint. This fingerprint will be used when migrating clients.
Clients
All clients with supported product installations (for example, ProtectFile, and CTE) can be managed on the CipherTrust Manager. A Administrator can register clients (except ProtectFile clients) with the CipherTrust Manager, view registered clients, view and modify details, revoke registrations, renew clients, and delete clients when they are no longer needed.
The following table lists the parameters that are required when managing a client on the CipherTrust Manager:
Parameter | Description |
---|---|
Name | Name for the client to display on the CipherTrust Manager. |
Registration Token | Registration token to register the client with the CipherTrust Manager. |
Certificate Signing Request (CSR) | CSR to be signed by the CipherTrust Manager. |
Warning
As soon as a client is deleted from the CipherTrust Manager, all communication between the CipherTrust Manager and the client will stop immediately. It is recommended that the clients are decrypted before deletion, otherwise the encrypted data will become inaccessible.
Public Clients
The CipherTrust Manager pre-registers the following public clients:
ksctl
NAE
Web-UI
API playground
These public clients are shipped with the hard-coded client ids and names as follows:
client id | client name |
---|---|
c5890024-a6d4-408d-a592-5d4d5807c722 | nae |
17771cf2-f80b-4eb5-a19b-a2d0032179c3 | web-ui |
5ffb6fac-2cb5-4b91-8183-e20ad3b62577 | ksctl |
837c840d-75dd-4b4f-a318-79cb16ca248d | api-playground |
The client ids are pre-embedded in the respective public clients. When public clients call the /v1/auth/tokens endpoint API to generate a registration token, it includes the client_id
parameter with the password
grant type. The client_id
and client_name
are present in the issued JWT after the successful authentication.
The CipherTrust Manager allows you to embed the above client ids into the generic "public rest clients". Make sure to include the client id during the /v1/auth/tokens endpoint API call so that the CipherTrust Manager can recognize the client as a registered public client instead of an "unregistered" client. This helps to track and harden user delegations.
Renew Client Certificates
The CipherTrust Manager allows you to renew the certificate of a registered CipherTrust Manager client. The CipherTrust Manager provides the following renewal methods:
Admin's Renew Route - A member of the
Client Admins
oradmin
group can renew the certificate for a client.Self-renew Route - An authenticated client that is a part of
All Clients
group can renew its own client certificate.
Note
• Self renewal is only supported for certificates signed by a Local CA of the CipherTrust Manager.
•The grant_type
of the client authentication should be client_credentials
.
After the successful renewal, the renewed certificate and the key (optional) will be shared in the response. The authentication of the renewed client certificate is based on the Subject DN
of the certificate.
Note
After the renewal of client certificates, the CipherTrust Manager continues to allow old client certificates unless they are revoked or expired.
A CipherTrust Manager client certificate cannot be renewed if it is revoked.
The following table lists the parameters that are required to renew client certificates:
Parameter | Description |
---|---|
cert_duration | Duration (in days) for which the CipherTrust Manager client certificate is valid. The default duration is 730 days. It is recommended not to use a duration longer than that. The certificate duration shouldn't be more than the CA duration. However, if the certificate duration exceeds the CA duration, the certificate duration is automatically set to CA's duration. |
csr | CSR to be signed by one of the Local CAs (the CA which is the issuer of the current client certificate) of the CipherTrust Manager. |
do_not_modify_subject_dn | Specifies if Subject DN in the CSR is allowed to be modified or not. If this flag is set to true , then Subject DN must be unique across all the CipherTrust Manager clients, otherwise renewal will not be allowed. The default value is false . For details, refer to the section Renewing Local CA Clients. |
ext_cert | New client certificate signed by an external CA to renew an existing CipherTrust Manager client. |
subject_dn_field_to_modify | This field is used to make Subject DN unique so that the client can be identified uniquely. The default value is UID . For details, refer to the section Renewing Local CA Clients. |
subject_dn_template | CSR parameters used to generate a CSR for client certificate. |
key_gen_params | Parameters (algorithm, size, private_key_bytes, and so on) are used to generate and optionally encrypt the private key. |
Renewing Local CA Clients
A client certificate can be renewed using one of the following methods:
Client CSR
You can pass the CSR with
do_not_modify_subject_dn
flag. This flag specifies if theSubject DN
in the CSR is allowed to be modified by the CipherTrust Manager as part of renewal or not.If
do_not_modify_subject_dn
is set tofalse
, the server assignsclient_id
toSubject DN
of the field decided by thesubject_dn_field_to_modify
parameter.For example:
"/CN=admin/UID=1a26fd25-0c28-4afa-b392-a4fa970604a1"
This ensures that
Subject DN
is unique for each renewed client.However, if
do_not_modify_subject_dn
is set totrue
, the client does not permit the server to modifySubject DN
in the CSR. In this case, the client needs to provide a CSR withSubject DN
which is unique on the CipherTrust Manager.Note
It is highly recommended to set the
do_not_modify_subject_dn
field to false unless there are constraints preventing modifications in the CSR.Server CSR
The CSR parameters (
subject_dn_template
) and key generation parameters (key_gen_params
) can be passed to generate and optionally encrypt the private key.The server assigns
client_id
toSubject DN
of the field decided by thesubject_dn_field_to_modify
parameter. This ensures thatSubject DN
is unique for each renewed client.Without Client and Server CSRs
When the client CSR and server CSR parameters are not provided, the renewal parameters are taken from an internal client profile used at the time of registration. If no associated profile is found, the renewal fails.
The server assigns
client_id
toSubject DN
of the field decided by thesubject_dn_field_to_modify
parameter. This ensures thatSubject DN
is unique for each renewed client.
In case of renewing a client that is issued by a local CA, you can specify the certificate duration. The default value (duration) is 730 days.
Following are the possible values of the subject_dn_field_to_modify
field:
UID (
userid
)CN (
commonName
)SN (
serialNumber
)DNQ (
dnQualifier
)OU (
organizationalUnit
)
If none of the fields is selected, by default the UID
is used to modify the Subject DN
.
Warning
If any of these fields (except OU
) is selected, the original field values will be overridden by the CipherTrust Manager.
If OU
is selected, the OU
will be appended to Subject DN
with other attributes.
Note
It is recommended to select a field that is not already a part of CSR or CSR parameters (that is, select a not-in-use field).
Renewing External CA Clients
When renewing a client certificate that is issued by an external CA, you need to provide the new certificate signed by the external CA in the request. The renewed certificate must have a unique Subject DN
for each client. Also, Subject DN
of the new certificate should match Subject DN
of the old client's certificate.
Renew Client Certificates using ksctl
To renew client certificate, run:
Syntax
Example Request 1 for Local CA
Example Response 1
Example Request 2 for Local CA
Example Response
Example Request 3 for Local CA
Example Response 3
Example Request 4 for Local CA
Example Response 4
Example Request 5 for Local CA
The CSR file must be in the PEM
format as:
Example Response 5
Example Request 6 for External CA
The CSR file must be in the PEM
format as:
Example Response 6
Self-Renew Client Certificates using ksctl
To self-renew client certificate, run:
Syntax
Example Request 1
Example Response 1
Example Request 2
Example Response 2
Example Request 3
Example Response 3
Example Request 4
The certificate file must be in the PEM
format as:
Example Response 4
Example Request 5
Example Response 5
Client Certificate Expiration Check
The CipherTrust Manager inspects the expiration date of all the registered client's certificates everyday, at a preset system time to log the record.
The CipherTrust Manager then creates list of certificates based on their expiration date:
Certificates whose expiration dates are within 91 days.
This list is logged in the Records section once every week.
Certificates whose expiration dates are within 7 days.
This list is logged in the Records section once every day.
Certificates that are already expired.
This list is logged in the Records section once every day.
You can also create alarm triggers for these records. For more details, go to Creating Alarm Trigger for Client Certificate Expiration.