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 the update of the 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 executable files \#start_util.cmd and !key-store-admin.cmd. File names
Bold The Key Store Administrator utility is a part of the RadixWare platform designated to manage keystores and certificate stores. Names of software products; names of user interface elements; names of operations; operation parameters
Bold separated by vertical bar The operation is executed using the menu item File / Open PKCS 11 Keystore. Path to the menu item
Underlined Toolbar Hyperlink to a subsection or paragraph within the document
Note.jpg Note.jpgThe operation is used for the file keystore only. Notes
Example.jpg Example.jpgExample of the command using the SSH protocol authentication. Examples


Abbreviations

CA - Certification Authority

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:

  1. Utility overview
  2. Description of how the utility is installed and started
  3. Description of the user interface
  4. Description of the main utility operations
  5. Examples of how the utility is used.

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 ensure the information security in the system implemented on the RadixWare platform, the cryptographic system with public keys is used. This system handles the following tasks:

  • Provides a secure connection between the client and server via the TLS protocol
  • Enables to use the digital signature for update packages of the software product and verifies this signature.

The Key Store Administrator utility is a part of the RadixWare platform designated to manage keystores and certificate stores.

The utility performs the following functions:

  • Generates own RSA keys
  • Generates and exports own keys to the PKCS12 file
  • Creates self-signed certificates for own keys
  • Creates a request for a certificate for the own key
  • Prepares and issues key certificates
  • Imports the certificate for the own key
  • Imports / exports trusted certificates
  • Imports the key and its certificates from the PKCS12 file

This functionality enables to deploy the public key infrastructure (PKI) with own Certification Authority.

The utility supports the following keystore types:

  • JCEKS file
  • Hardware store based on PKCS#11 standard

The Key Store Administrator utility functions as an independent component of the RadixWare platform and is a module of the RadixWare Manager application enabling to set up the mechanism used to sign / verify digital signatures for the software product update packages.

Utility Installation and Startup

System Requirements

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

Note.jpgFor Windows 64-bit, PKCS11 keystores are not supported.

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

Utility Installation

The Key Store Administrator utility is supplied as part of the software product installation package and does not require additional installation. For details on how to install the software product, refer to RadixWare. Software Products Installation and Upgrade Technology.


Starting Utility from Command Line

The utility is started using the RadixWare Starter (starter.jar file).

To start the utility from the command line:

1.Extract the starter.jar file from the repository containing the software product and save it to the local drive of the workstation 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 values defined

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

Example.jpgExample of the command 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 to access the repository - svn,

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

parameter -sshKeyPasswordInteractive defines the request for the password to access 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.

Executing the command opens the main window of the utility:

Lounch keystoreadmin 2.jpg


Starting Utility Using Command File

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

To start the utility in Windows OS:

1.Extract the files starter.jar, \#start_util.cmd and !key-store-admin.cmd from the repository where the software product is installed and save them to the local drive of the workstation. The command files are located in the following directory of the repository: .../<Install URI\*>/etc/osScripts/prod/, where Install URI\* is the name of the software product.

2.Correct the startup parameters in these files.

3.Run the command file !key-store-admin.cmd.


Starting Utility in RadixWare Manager

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

Lounch keyStoreAdmin.jpg

User Interface

The main window of the Key Store Administrator looks as follows:

user_interface16.jpg

The main window consists of:

  • 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 a file keystore

Open File Keystore

+

Opens the file store used for JCEKS keys

Open PKCS#11 Keystore

+

Opens the file store used for PKCS#11 keys

Save Keystore

+

Saves the changes made to the keystore (Ctrl+S)

Exit

-

Exits the Key Store Administrator utility (Ctrl+Q)

Settings

Distinguished Name

-

Enables to enter the data of the certificate owner:

  • User name. The user name to be used for identification.
  • Organizational unit. The name of the organizational unit.
  • Organizational name. The name of the organization.
  • Locality. The name of the locality.
  • State. The name of the region / state.
  • Country. The name of the country.

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

Help

About...

-

Outputs the 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 a file keystore

user_interface2.jpg

Open File Keystore

Opens the file store used for JCEKS keys

user_interface3.jpg

Open PKCS#11 Keystore

Opens the file store used for PKCS#11 keys

user_interface4.jpg

Save Keystore

Saves the changes made to the keystore

user_interface5.jpg

Change Keystore Password

Changes the keystore 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 keystore

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 a certificate request

user_interface13.jpg

Receive Certificate

Receives the certificate from the Certification Authority

user_interface14.jpg

Sign Client's Certificate

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

user_interface24.jpg

Generate 3DES Key

Generates a 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 keystore item.

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

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


Working Area

The working area shows the keystore content including:

  • Own key with the self-signed certificate
  • Own key with the external certificate
  • Trusted certificate

The keystore items have a tree-like structure:

- Keystore 
 - Key 
  - Certificate chain (it can include own certificate, CA certificate and certificates of intermediate authorities): 
   - Certificate 
   - .... 
   - .... 
 - Trusted certificate


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

The table below describes the keystore items:

Icon

Item

Description

user_interface17.jpg

Keystore

The item name indicates the keystore location

user_interface18.jpg

Key

The item name contains:

  • Key name
  • Encryption algorithm (Algorithm)
  • Key length (Length)
  • Key check value (Check value). The item is displayed for 3DES keys only.

user_interface19.jpg

Certificate Chain

The item name indicates the number of certificates in the chain.

user_interface20.jpg

Certificate

The item name contains:

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

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 item name indicates the certificate name. The item contains the Certificate item of the Trusted certificate type (see above).

Main Utility Operations

Keystore Management Operations

The Key Store Administrator utility provides the following operations to manage the keystore:

Operation

Button

Function

Create File Keystore

user_interface1.jpg

Creates a file store for JCEKS keys.

The operation can be executed by:

  • Clicking the respective button on the utility toolbar
  • Using the menu File | Create File Keystore

Operation parameters:

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

note.jpgThis parameter is used to define the password to access the keystore and password for the keys that will be located in this store.

  • Password confirmation. Confirm the entered password.

As a result of the command execution, the working area of the utility will show the record indicating the keystore location.

Open File Keystore

user_interface2.jpg

Opens the keystore.

The operation can be executed by:

  • Clicking the respective button on the utility toolbar
  • Using the menu File | Open File Keystore

Operation parameters:

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

As a result of the command execution, the working area of the utility will show the keystore content.

Open PKCS#11 Keystore

user_interface3.jpg

Opens the hardware keystore.

note.jpgWhen the system is used for the first time, install the drivers for the electronic device.

The operation can be executed by:

  • Clicking the respective button on the utility toolbar
  • Using the menu File | Open PKCS#11 Keystore

To open the keystore, specify:

  • Location of the configuration file of the electronic device. The file name format is "*.cfg".
  • Password to access the electronic device.

Save Keystore

user_interface4.jpg

Saves the changes made to the keystore

Change Keystore Password

user_interface5.jpg

Changes the keystore password.

note.jpgThe operation is used for the file store only.

To change the password, open the required keystore.

Operation parameters:

  • New password. The new password.
  • Confirmation. Confirm the entered password.

Key Management Operations

The Key Store Administrator utility provides the following operations to manage keys:

Operation

Button

Function

Generate Key Pair

user_interface6.jpg

Generates a pair of RSA keys in the current keystore.

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 stores (see below).

Operation parameters:

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

note.jpgThe certificate attribute containing the user account is set up in System Settings | Systems | EAS | Certificate attribute that contains login name parameter.

note.jpgThe information on the certificate owner can be entered in advance (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 the drop-down list. The default value is 1024.
    • Public exponent. The public exponent of the key. The value is selected from the 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 self-signed certificate of the key (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 a store 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 the drop-down list. The default value is 1024.
    • Public exponent. The public exponent of the key. The value is selected from the 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 self-signed certificate of the key (in days).
  • In the Export Key Pair to PKCS#12 Keystore dialog box, perform the following actions:
    • PKCS#12 keystore file. Click basic_options.jpg to open the dialog box for file selection. Specify the keystore file location. The file name format is "*.p12".
    • PKCS#12 keystore password. Enter the keystore 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 chain of certificates to the PKCS#12 file.

Operation parameters:

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

The operations of export / import of the key pair to the PKCS#12 file are used to:

  • Transport the keys between the keystores
  • Back up the keys

Import Key Pair from PKCS#12 Keystore

user_interface9.jpg

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

Operation parameters:

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

As a result of the command execution, the keystore shows the public key with its chain of certificates.

Generate 3DES Key

user_interface24.jpg

Generates a 3DES key in the current keystore.

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 keystore from several clear-text components.

The key is imported using the Key Component # Input dialog box. Operation parameters:

  • Component. The clear-text value of the next key component. It should consist of 32 hexadecimal digits. For security reasons, character "●" is displayed in the field instead of the characters being entered.
  • Length. The length of the entered component part.
  • Check value. The check value of the key component.

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 built 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 check value of the key.

Certificate Management Operations

The Key Store Administrator utility provides the following operations to manage certificates:

Operation

Button

Function

Export Certificate

user_interface10.jpg

Exports the certificate to be further loaded to other keystores as a trusted certificate. The operation can be used if, for example, the utility functions as CA.

Operation parameters:

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

Load Trusted Certificate

user_interface11.jpg

Loads the trusted certificate to the current keystore.

Operation parameters:

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

When loading the certificate, the user is offered to check the trusted certificate data containing the CA information and certificate prints. The certificate is loaded to the keystore after the data validity is confirmed by the user.

Prepare Certificate Request

user_interface12.jpg

Generates a 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 basic_options.jpg to specify the location of the file with the certificate request. The file name format is "*.csr".

The request is generated in PKCS#10 format.

Receive Certificate

user_interface13.jpg

Loads the certificate signed by the CA to the current keystore.

Operation parameters:

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

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

Sign Client's Certificate

user_interface14.jpg

Signs the Customer certificate. The operation can be used if the utility functions as CA.

Operation parameters:

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

Examples of Using Utility

Setting up Keystore on Server for Secure Connection via TLS Protocol

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

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

1.Define the keystore:

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

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

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


Loading Trusted Certificate when Setting up Digital Signature Verification

The update packages for the RadixWare-based software products contain the digital signature. This enables to control the integrity of the received zip files, protect them against unauthorized changes, and check whether the signature belongs to the owner of the digital signature key certificate.

The RadixWare Manager application automatically checks the data of the digital signature of the zip file when loading the software product update package to the repository of the Organization. To be able to verify the digital signature, it is necessary to set up a keystore on the workstation of the administrator responsible for the software product installation and upgrade in the Organization. The list of trusted certificates in this keystore should contain the digital certificate of the Organization the update packages are signed by (software product vendor). The keystore is set up and managed using the RadixWare Manager application (editor of the project parameters | Key Store tab | Key Store Administrator button).

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