Syncplicity Support

Search our knowledgebase to get the help you need, today

Follow

Working with keystores

This topic describes how to work with keystore files by using the keytool command line utility. This utility is part of the JDK package and is already available on the Storage Connector virtual machine.

The examples below cover PKSC12 keystore type usage. When working with the other supported keystore types (JCEKS, JKS, DKS or PKCS11) the commands might require modifications. Please familiarize yourself with the help documentation of the keytool utility.

Security concerns related to keystore password

Keystore content is accessed using the keystore password. Keytool will require the password to be provided either via interactive command line prompt or via the -storepass <password>  command option. If provided via the command option, the password will remain in clear text in the shell history. In that case, please consider clearing the shell history once your tasks with the keystore are completed.

Limitations and best practices when working with keytool and keystores

Please consider the following:

  • When configuring new connector instances always start with an empty keystore.
  • Keytool doesn't support importing configurations that contain new lines.
  • When inserting JSON values, minify them and paste them without any quotation marks. For minifying one may use: cat file.json | jq - c
  • Keytool doesn't support inline password insertion for PKCS12 keystores, so the configuration values need to be added via the shell prompt.
  • The configuration values stored in the keystore file must consist only of printable ASCII characters.

Useful commands when working with keytool

Create an empty keystore

The only possible way to create an empty keystore with keytool is to create a non-empty one and then delete the content:

keytool -genkey -alias tmp -keystore <keystore_file> -dname "CN=tmp" -storetype pkcs12 [-storepass <password>]

keytool -delete -alias tmp -keystore <keystore_file> [-storepass <password>]

Example:

$ keytool -genkey -alias tmp -keystore /etc/syncp-storage/keyStore.p12 -dname "CN=tmp" -storetype pkcs12 -storepass password
$ keytool -delete -alias tmp -keystore /etc/syncp-storage/keyStore.p12 -storepass password
$ keytool -v -list -keystore /etc/syncp-storage/keyStore.p12 -storepass password -storetype pkcs12
Keystore type: PKCS12
Keystore provider: SunJSSE

Your keystore contains 0 entries

See the below example for further context.

View contents of a keystore

The following command displays the content of a keystore. A single entry can be displayed by using the -alias option. It is not possible to see the stored configuration values via keytool but only the names.

keytool -list -v -keystore <keystore_file> -storetype pkcs12 [-storepass <password>]

keytool -list -v -keystore <keystore_file> -alias <configuration_name> -storetype pkcs12 [-storepass <password>]

Example:

$ keytool -v -list -keystore /etc/syncp-storage/keyStore.p12 -storepass password -storetype pkcs12
Keystore type: PKCS12
Keystore provider: SunJSSE

Your keystore contains 2 entries

Alias name: server
Creation date: May 6, 2020
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=tmp

.... (content omitted)

Alias name: syncplicity.ws.accesskey
Creation date: May 6, 2020
Entry type: SecretKeyEntry


*******************************************
*******************************************

In this example the keystore type is confirmed to be PKCS12 (see the first line of the command output) and the keystore contains 2 entries: a certificate and a configuration secret.

Add a configuration parameter

By using the following command, you can add or update the contents of a keystore. The name of the configuration is specified using the -alias option. The configuration value must be typed in the shell.

keytool -v -keystore <keystore_file> -storetype pkcs12 -importpass -alias <configuration_name> [-storepass <password>]

Example:

$ keytool -v -keystore /etc/syncp-storage/keyStore.p12 -storetype pkcs12 -storepass password -importpass -alias syncplicity.ws.accesskey
Enter the password to be stored:  
Re-enter password: 
Generated PBE secret key

Remove a configuration parameter

The following command removes the keystore entry. The name of the configuration to be removed is specified via the -alias option.

keytool -delete -alias <configuration_name> -keystore <keystore_file> [-storepass <password>]

Example:

$ keytool -delete -alias syncplicity.ws.accesskey -keystore /etc/syncp-storage/keyStore.p12 -storepass password

Update a configuration parameter

Update of an existing configuration parameter in a keystore is not possible. In order to be updated, first it has to be removed, then re-added again:

keytool -delete -alias <configuration_name> -keystore <keystore_file> [-storepass <password>]

keytool -v -keystore <keystore_file> -storetype pkcs12 -importpass -alias <configuration_name> [-storepass <password>]

Example:

$ keytool -delete -alias syncplicity.ws.accesskey -keystore /etc/syncp-storage/keyStore.p12 -storepass password
$ keytool -v -keystore /etc/syncp-storage/keyStore.p12 -storetype pkcs12 -importpass -alias syncplicity.ws.accesskey -storepass password
Enter the password to be stored:  
Re-enter password: 
Generated PBE secret key

Change the keystore password

Changing the password of an existing  keystore can be done via the following command:

keytool -storepasswd -keystore <keystore_file> -storetype pkcs12 [-storepass <password>]

Example:

$ keytool -storepasswd -keystore /etc/syncp-storage/keyStore.p12 -storetype pkcs12 -storepass password
New keystore password: 
Re-enter new keystore password: 

Change a configuration name

Changing a configuration name and keeping the existing value is achieved via the following command:

keytool -changealias -alias <configuration_name_1> -destalias <configuration_name_2> -keystore <keystore_file> -storetype pkcs12 [-storepass <password>]

Example:

$ keytool -v -changealias -alias syncplicity.ws.accesskey -destalias syncplicity.ws.accesskey.1 -keystore /etc/syncp-storage/keyStore.p12 -storepass password
[Storing keyStore.p12]

Import a certificate from a file

Adding a certificate in a keystore can be done using the following command:

keytool -import -alias <configuration_name> -file <certificate_file> -keystore <keystore_file> [-storepass <password>]

Example:

$ keytool -import -alias server -file syncplicity.pem -keystore /etc/syncp-storage/keyStore.p12 -storepass password 
Owner: CN=*.syncplicity.com, OU=Operations, O="Syncplicity, Inc.", L=Phoenix, ST=Arizona, C=US
Issuer: CN=DigiCert SHA2 Secure Server CA, O=DigiCert Inc, C=US

.... (certificate content omitted)                      

Trust this certificate? [no]:  yes
Certificate was added to keystore

Import a configuration from another keystore

Importing a configuration from another keystore file is done with the following command:

keytool -importkeystore -srckeystore <source_keystore_file> [-srcstorepass <password> -srckeypass <password>] -destkeystore <destination_keystore_file> -deststoretype PKCS12 -srcalias <configuration_name> -destalias <configuration_name> [-deststorepass <password> -destkeypass <password>]

Example:

keytool -importkeystore -srckeystore /etc/syncp-storage/keyStore_old.p12 -srcstorepass password  -srckeypass password -destkeystore /etc/syncp-storage/keyStore.p12 -deststoretype PKCS12 -srcalias syncplicity.ws.accesskey -destalias syncplicity.ws.accesskey -deststorepass password -destkeypass password
Importing keyStore_old.p12 to keyStore.p12...
Powered by Zendesk