RadixWare Administrator Guide/RadixWare Key Store Administrator

From RadixWiki
Jump to: navigation, search

Revision History

Date Description of Changes
03.06.2019 Supported the facility to start the application on Java SE 11.

Updated section Utility Installation and Startup

19.03.2019 Due to update of system core components, eliminated the facility to start applications running on Java JDK 1.7.x.

Updated section Utility Installation and Startup


Conventions and Abbreviations

Conventions

Convention Example Applies To
Italic The software product distribution kit includes the \#start_util.cmd and !key-store-admin.cmd executable files File names
Bold The Key Store Administrator utility that is a part of the RadixWare platform is used to manage the key storages and system certificates Terms introduced for the first time; names of the software products; names of the user interface elements, application units, parameters, fields, operations, tags
Bold separated by vertical bar The operation is executed by means of the File / Open PKCS 11 Keystore menu Path to the menu item, dialog box, navigation tree branch
Underlined Toolbar Hyperlink to a subsection or paragraph within the document
Note.jpg Note.jpgThe operation is applied only for the file key storage Notes
Example.jpg Example.jpgExample of writing the command using the SSH protocol authentication. Examples


Abbreviations

CA - Certification Authority

DS - Digital Signature

OS - Operating System

Introduction

The document hereunder guides through the Key Store Administrator utility that is a part of the RadixWare platform.

The document contains the following information:

  1. The utility overview
  2. The utility installation and startup
  3. The user interface description
  4. The description of the main utility operations
  5. The examples of using the utility

The document is intended for the administrator who is responsible for the system installation and configuration.


Related Documents

# Document name Description
1 RadixWare Explorer. User Guide The document describes the RadixWare Desktop Explorer and RadixWare Web Explorer application facilities and methods of executing various operations.
2 RadixWare Starter. Administrator Guide The document describes the RadixWare Starter application and its startup procedure.
3 RadixWare. Software Products Installation and Upgrade Technology The document describes the RadixWare Manager application and procedures of installing and updating the software products by means of RadixWare Manager


Overview

To provide the information security in the system implemented on the RadixWare platform, the cryptographic system with public keys is used. The system serves the following purposes:

  • Providing the secure connection between client and server via TLS protocol
  • Creating the mechanism of signing the software service packs with digital signature (DS) and checking the digital signature

The Key Store Administrator utility is used to manage the key and system certificate storages, it is a part of the RadixWare platform.

The utility performs the following functions:

  • Generating own RSA keys
  • Generating and exporting own keys to the PKCS12 file
  • Creating the self-signed certificates for own key
  • Creating the request to receive the certificate for own key
  • Preparing and issuing the key certificates
  • Loading the certificate for own key
  • Loading / unloading the trusted certificates
  • Loading the key and its certificates from the PKCS12 file

The functionality allows to build the public key infrastructure (PKI) with its own Certification Authority.

The utility supports the following key storage types:

  • the JCEKS file
  • hardware storage on the basis of the PKCS\#11 standard

The Key Store Administrator utility functions as an independent component of the RadixWare platform, it is the RadixWare Manager application unit used to set up the mechanism for signing / checking digital signatures of the software service packs.

Utility Installation and Startup

System Requirements The Key Store Administrator utility operates on all platforms supporting Java: Windows, Linux, Unix, etc.

Note.jpgThe packages for Windows 64-bit do not support the PKCS11 key storages.

To work with the utility, Java SE version 8 or 11 must be installed. It is recommended to install Java SE Development Kit and use the latest Java SE version.

Utility Installation Key Store Administrator is supplied together with the software product installation package and does not require additional installation. For the software installation description, refer to RadixWare. Software Products Installation and Upgrade Technology.


Utility Startup from Command Line

The utility is started up by means of RadixWare Starter (the starter.jar file). To start it up from the command line, perform the following actions: 1.Extract the starter.jar file from the repository with the installed software product and save it to the workstation local disk where the utility will be used. 2.Execute the following command:

java.exe - <parameter_JVM> -jar starter.jar <parameter>=<value>, where

<parameter_JVM>|- JVM parameters (for details, refer to the JVM documentation)

<parameter>=<value>|- startup parameters with the set values

For the startup parameters, refer to RadixWare Starter. Administrator Guide.

Example.jpgExample of the command written with the use of the SSH authentication: java.exe -Xmx512m -jar starter.jar -svnHomeUrl=''svn+ssh://svn.repository.local/txrbs/prod'' -topLayerUri=org.productUpperLayer -authUser=svn -sshKeyFile=C:\PRODUCT\svn.pem -sshKeyPasswordInteractive org.radixware.kernel.utils.keyStoreAdmin.KeyStoreAdmin, where

value -Xmx512m defines the parameters for JVM,

parameter -svnHomeUrl defines URL of the software product repository - ''svn+ssh://svn.repository.local/txrbs/prod'',

parameter -topLayerUri defines the software product URI - org.productUpperLayer,

parameter -authUser defines the user name for access to the repository - svn,

parameter -sshKeyFile defines the path to the SSH public key for authentication - C:\PRODUCT\svn.pem,

parameter -sshKeyPasswordInteractive defines the password request to access to the repository in the interactive mode,

value org.radixware.kernel.utils.keyStoreAdmin.KeyStoreAdmin defines the main class of the application to be started (mandatory).


Note.jpgPrior to the command execution, add JAVA_HOME to the environment variables.

The command execution opens the utility main window:

Lounch keystoreadmin 2.jpg


Utility Startup by Command File

Key Store Administrator can be started up by means of the command file. As a rule, the software distribution kit for Windows OS includes the following specific files: \#start_util.cmd and !key-store-admin.cmd.

To start up the utility in Windows OS, perform the following actions: 1.Extract the starter.jar, \#start_util.cmd and !key-store-admin.cmd files from the repository where the software product is installed and save them to the workstation local disk. The command files are located in the following repository: .../<Install URI\*>/etc/osScripts/prod/, where Install URI\* is a software product name. 2.Correct the startup parameters in the file data. 3.Run the command file !key-store-admin.cmd.

Utility Startup in RadixWare Manager Application

The utility is started up on the Key Store page of the project parameters editor by clicking the Key Store Administrator button:

Lounch keystoreadmin.jpg

User Interface

The Key Store Administrator main window:

user_interface16.jpg

The utility main window contains the following items:

  • Main menu
  • Toolbar
  • Working area


Main Menu

The table below describes the menu items:

Menu Item

Submenu Item

Button on Toolbar

Function

File

Create File Keystore

+

Creates the file storage

Open File Keystore

+

Opens the JCEKS file storage for the keys

Open PKCS#11 Keystore

+

Opens the PKCS#11 file storage for the keys

Save Keystore

+

Saves the changes in the key storage - Ctrl+S

Exit

-

Finishes work with Key Store Administrator - Ctrl+Q

Settings

Distinguished Name

-

Enters data about the certificate owner:

  • User name. The user name that will be used for identification.
  • Organizational unit. The organization unit name.
  • Organizational name. The organization name.
  • Locality. The locality name.
  • State. The region / state name.
  • Country. The country name.

The Show at every key pair generation flag. If the flag is set, the certificate owner data will be displayed every time the RSA keys are generated.

Help

About...

-

Displays information on the Key Store Administrator utility


Toolbar

The table below describes the utility toolbar buttons:

Button

Command

Function

user_interface1.jpg

Create File Keystore

Creates the file storage

user_interface2.jpg

Open File Keystore

Opens the file storage for the JCEKS keys

user_interface3.jpg

Open PKCS#11 Keystore

Opens the file storage for the PKCS#11 keys

user_interface4.jpg

Save Keystore

Saves the changes in the key storage

user_interface5.jpg

Change Keystore Password

Changes the key storage password

user_interface6.jpg

Generate Key Pair

Generates a pair of keys

user_interface7.jpg

Generate Key Pair and Export to PKCS#12 Keystore

Generates a pair of keys and exports it to the PKCS#12 file

user_interface8.jpg

Export Key Pair to PKCS#12 Keystore

Exports a pair of keys to the PKCS#12 file

user_interface9.jpg

Import Key Pair from PKCS#12 Keystore

Imports a pair of keys from the PKCS#12 storage

user_interface10.jpg

Export Certificate

Exports the certificate

user_interface11.jpg

Load Trusted Certificate

Loads the trusted certificate

user_interface12.jpg

Prepare Certificate Request

Generates the certificate request

user_interface13.jpg

Receive Certificate

Receives the certificate from the Certification Authority

user_interface14.jpg

Sign Client's Certificate

Signs the Client certificate (hereinafter the Customer is an organization or the organizational unit which interacts with the Certification Authority)

user_interface24.jpg

Generate 3DES Key

Generates the key for the 3DES encryption algorithm

user_interface25.jpg

Import 3DES Key

Imports the key for the 3DES encryption algorithm from several clear-text components

user_interface15.jpg

Delete Entry

Deletes the key storage item.

In the Keystore Entity Deleted dialog box, select the item from the drop-down list.

For details on the utility operations, refer to Utility Main Operations.


Working Area

The working area displays the key storage contents that can include the following items:

  • own key with the self-signed certificate
  • own key with the external certificate
  • trusted certificate

The storage items form a tree-structure:

- Key storage

- Key

- Certificate chain (it can include own certificate, CA certificate and the certificates of the intermediate Authorirties):

- Certificate

- ....

- ....

- Trusted certificate


To open the item and view its contents click user_interface23.jpg / user_interface22.jpg.

The table below describes the key storage items:

Icon

Item

Description

user_interface17.jpg

Key Storage

The item title displays the storage location

user_interface18.jpg

Key

The item title contains the following:

  • The key title
  • Algorithm. The encryption algorithm.
  • Length. The key length.
  • Check value. The key check value. The item is displayed only for the 3DES keys.

user_interface19.jpg

Certificates Chain

The title displays the number of certificates in the chain

user_interface20.jpg

Certificate

The item title contains the following:

  • The certificate type:
    • Own certificate - own certificate.
    • Trusted certificate - trusted certificate.
    • CA certificate - CA certificate or the intermediate CA certificate.
  • Serial number. The certificate digital identifier.

Certificate attributes:

  • Subject. The certificate owner data.
  • Issuer. The certificate issuer data.
  • Not before, Not after. The certificate validity period.
  • MD5 fingerprint. The certificate MD5 hash value.
  • SHA1 fingerprint. The certificate SHA1 hash value.

user_interface21.jpg

Trusted Certificate

The title displays the certificate name. The item contains the Certificate item of the Trusted certificate type (see above).

Utility Main Operations

Key Storage Management Operations

The Key Store Administrator utility provides the following operations of managing the key storage:

Operation

Button

Function

Create File Keystore

user_interface1.jpg

Creates the JCEKS key file storage.

The operation can be executed by one of the following methods:

  • clicking the button on the utility toolbar
  • using the menu File | Create File Keystore

Operation parameters:

  • Keystore file. The button basic_options.jpg opens the file selection dialog box. Specify the location for the key file storage. The file name format is "*.jceks".
  • Password. The storage password.

note.jpgThe parameter defines the password for the storage and password for the keys that will be located in the storage.

  • Password confirmation. The confirmation of the entered password.

As a result of the command execution, the working area of the utility window will display the record specifying the storage location.

Open File Keystore

user_interface2.jpg

Opens the created key file storage.

The operation can be executed by:

  • clicking the button on the utility toolbar
  • using the menu File | Open File Keystore

Operation parameters:

  • Keystore file. Click the button basic_options.jpg to specify the key storage file location. The file name format is "*.jceks".
  • Password. The storage password.

As a result of the command execution, the working area of the utility window displays the storage contents.

Open PKCS#11 Keystore

user_interface3.jpg

Opens the hardware key storage.

note.jpgWhen using the system for the first time, set up the electronic device drivers.

The operation can be executed by:

  • clicking the button on the utility toolbar
  • using the menu File | Open PKCS#11 Keystore

To open the storage, specify the following:

  • The location of the electronic device configuration file. The file name format is "*.cfg".
  • The electronic device access password.

Save Keystore

user_interface4.jpg

Saves changes in the key storage

Change Keystore Password

user_interface5.jpg

Changes the key storage access password.

note.jpgThe operation is applied only to the file key storage.

To change the password, open the required key storage.

Operation parameters:

  • New password. The new access password.
  • Confirmation. The confirmation of the entered password.

Key Management Operations

The Key Store Administrator utility provides the following operations of managing the keys:

Operation

Button

Function

Generate Key Pair

user_interface6.jpg

Generates a pair of RSA keys in the current key storage.

note.jpgWhen generating a pair of keys in the electronic device, the closed key cannot be further exported. Therefore, it is recommended to use the Generate Key Pair and Export to PKCS#12 Keystore operation for the hardware storages (see below).

Operation parameters:

  • In the Distinguished Name dialog box, enter the following information about the certificate owner:
    • User name. The user name.
    • Organizational unit. The organization unit name.
    • Organizational name. The organization name.
    • Locality. The locality name.
    • State. The region / state name.
    • Country. The country name.
    • UID. The identifier of the certificate user.

note.jpgTo set up the certificate attribute that will contain the user account, go to System Settings | Systems | EAS | Certificate attribute that contains login name parameter.

note.jpgThe information about the certificate owner can be entered in advance (the Settings | Distinguished Name menu item). Later, this information will be automatically added to the operation parameters.

  • In the Key Pair Generation dialog box:
    • Key length (bits). The key length. The value is selected from a drop-down list. The default value is 1024.
    • Public exponent. The key public exponent. The value is selected from a drop-down list: 3, 6557. The default value is 3.
    • Alias. The name under which the key will be stored.
    • Duration days. The validity period of the key self-signed certificate (in days).

As a result of the command execution, a pair of keys is generated, the public key is placed to the self-signed certificate.

Generate Key Pair and Export to PKCS#12 Keystore

user_interface7.jpg

Creates the storage in the PKCS#12 file and generates a pair of RSA keys.

Operation parameters:

  • In the Distinguished Name dialog box, enter the certificate owner information (similar to the Generate Key Pair operation).
  • In the Key Pair Generation dialog box, specify the following:
    • Key length (bits). The key length. The value is selected from a drop-down list. The default value is 1024.
    • Public exponent. The key public exponent. The value is selected from a drop-down list: 3, 6557. The default value is 3.
    • Alias. The name under which the key will be stored.
    • Duration days. The validity period of the key self-signed certificate (in days).
  • In the Export Key Pair to PKCS#12 Keystore dialog box, perform the following actions:
    • PKCS#12 keystore file. Clicking the button basic_options.jpg opens the file selection dialog box. Specify the location for the key file storage. The file name format is "*.p12".
    • PKCS#12 keystore password. Enter the storage password.
    • Password confirmation. Confirm the entered password.
    • Keypair alias. The key name. The parameter is not editable.

Export Key Pair to PKCS#12 Keystore

user_interface8.jpg

Exports the key pair and its certificates chain to the PKCS#12 file.

Operation parameters:

  • PKCS#12 keystore file. Click the button basic_options.jpg to specify the location for the file key storage. The file name format is "*.p12".
  • PKCS#12 keystore password. Enter the storage password.
  • Password confirmation. Confirm the entered password.
  • Keypair alias. From the drop-down list, select the name of the key to be exported.

The operations of exporting / importing the key pair to the PKCS#12 file are designed for the following purposes:

  • transporting the keys between the storages
  • backing up the keys

Import Key Pair from PKCS#12 Keystore

user_interface9.jpg

Imports the key pair and the certificates chain from the PKCS#12 file to the current storage.

Operation parameters:

  • PKCS#12 keystore file. Click the button basic_options.jpg to specify the location of the key file storage.
  • PKCS#12 keystore password. The storage password.
  • Keypair alias. The name under which the key will be stored.

As a result of the command execution, the key storage displays the public key with its certificates chain.

Generate 3DES Key

user_interface24.jpg

Generates the 3DES key in the current storage.

Operation parameters:

  • Alias. The name under which the generated key will be stored.

Import 3DES Key

user_interface25.jpg

Imports the 3DES key to the current storage from several clear-text components.

The key is imported by means of the Key Component # Input dialog box. Operation parameters:

  • Component. The clear-text value of the next key component. It must consist of 32 hexadecimal digits. For security reasons, the "●" symbols are displayed in the field instead of the entered ones.
  • Length. The length of the entered component part.
  • Check value. The key component check value.

The Next Component button is used to enter the next key component. The Build Key button imports the key from the entered components. The key is created by executing the bitwise XOR operation for all key components.

After the key component is entered, the DES Key Import dialog box opens. It contains the following parameters:

  • Alias. The name under which the imported key will be stored.
  • Check value. The key check value.

Certificate Management Operations

The Key Store Administrator utility provides the following operations of managing the certificates:

Operation

Button

Function

Export Certificate

user_interface10.jpg

Exports the certificate for its further loading to other storages as the trusted certificate. The operation can be applied if, for example, the utility functions as CA.

Operation parameters:

  • Alias. The name of the key whose certificate is exported.
  • Certificate file. The button basic_options.jpg opens the file selection dialog box. Specify the location of the file for the certificate to be exported. The file name format is "*.cer".

Load Trusted Certificate

user_interface11.jpg

Loads the trusted certificate in the current key storage.

Operation parameters:

  • Alias. The name under which the certificate will be stored.
  • Certificate file. Click the button basic_options.jpg to specify the location of the trusted certificate file. Possible file name formats: "*.cer", "*.pem".

During the loading, the user is offered to check the trusted certificate data containing the CA information and certificate prints. The certificate is loaded to the key storage after the data validity confirmation by the user.

Prepare Certificate Request

user_interface12.jpg

Generates the request to receive the certificate for the CA private key. Operation parameters:

  • Key alias. From the drop-down list, select the name of the key for which the certificate is required.
  • Request file. Click the button basic_options.jpg to specify the location for the certificate request file. The file name format is "*.csr".

The request is generated in the PKCS#10 format.

Receive Certificate

user_interface13.jpg

Loads the certificate signed by the CA to the current key storage.

Operation parameters:

  • Key alias. The name of the key for which the certificate is received.
  • Certificate file. Click the button basic_options.jpg to specify the location of the file where the received certificate is saved.

During the loading, the user is offered to check the trusted certificate data and the CA certificate data. As a result of the command execution, the certificates chain is received where the first certificate is a root one, and the second certificate is the CA certificate. The chain can contain the intermediate CA certificates.

Sign Client's Certificate

user_interface14.jpg

Signs the Client certificate. The operation can be applied if the utility functions as CA.

Operation parameters:

  • Signing key alias. Select the key for signing the certificate.
  • Request file. Click the button basic_options.jpg to select the certificate request file.
  • Certificate file. Click the button basic_options.jpg to specify the location of the signed certificate file. The file name format is "*.cer".
  • Duration (days). The key certificate validity period (in days).

Examples of Using Utility

Setting up Key Storage on Server when Establishing Secure Connection via TLS Protocol

The secure connection between the client and the server is implemented via the TLS protocol that provides the establishment of trust and encryption of the exchange data between two connection participants. For this purpose, a key storage must be created and properly set up for each participant. For the client, the storage is set up in Certificate Manager of the RadixWare Explorer application (Connections Manager | Security page | Certificates button). For details, refer to RadixWare Explorer. User Guide. On the server, the setup is performed by the Key Store Administrator utility.

The required settings for the key storage on the server (the server functions as CA):

1.Define the key storage:

  • for the file storage (JCEKS) - the Create File Keystore operation
  • for the hardware storage (PKCS11) - the Open PKCS11 Keystore operation

2.Generate a pair of the RSA keys with a self-signed certificate (the Generate Key Pair operation).

3.Export the self-signed certificate as a file (the Export Certificate operation). For the client, the certificate is loaded as the trusted one.

Loading Trusted Certificate When Setting Up DS Check

The RadixWare service packs contain the digital signature. It enables to control the integrity of the received zip files, secure them from unauthorized changes and check whether the signature belongs to the owner of the DS key certificate.

The RadixWare Manager application automatically checks the zip file DS data when loading the software product service packs to the Organization repository. To implement the DS check, it is required that the workstation of the administrator responsible for the software product installation and upgrade in the Organization has the set key storage containing the digital signature of the Organization that signed the software product service packs (the software product vendor). The key storages are set up and managed using the RadixWare Manager application (the project parameters editor | Key Store page | Key Store Administrator button).

For details, refer to RadixWare. Software Products Installation and Upgrade Technology.