Oracle Cloud Infrastructure Documentation

Keytool Commands

When using the keytool commands in this topic, ensure that you use the command flags discussed in Prerequisites for Keytool and Jarsigner.

Generate Key Pair

Use the -genkeypair flag to generate 1 private key and 1 public key in the DKMS HSM using keytool with JCE. The key is also stored in the local keystore by this operation.

To generate a key pair

Important: When you use the keytool command to generate a key pair or import an existing keystore, your Java Security configuration ensures that a public and private key are generated in the HSM card. If you're using the java.security file for this configuration, the OCI Dedicated KMS provider must be specified as priority 2 in the file for key pairs to be generated in the HSM.

Alternately, in the current directory, create a Java Security Override File file and add the OCI Dedicated KMS provider in the second position as security.provider.2. When executing a Keytool command, use the following option to specifiy the Java Security Override file:

-J-Djava.security.properties=<java_security_override_file>

See Add the JCE Provider to Java Security for more information on configuring Java Security.

Tip

The generated key pair can't be found using an alias in the Key Management Utility. Optionally, you can list keys before and after key generation to identify the new key in the HSM. This lets you easily delete the key in the HSM if you need to do so. Before creating a key pair, sign in to the HSM and create a list of existing handles. Then create a list after creating the key pair to find the handle of the new key pair. See Identifying the Handle of a New Key Pair or Secret Key in the HSM for instructions.

Command syntax:

keytool \
-J-cp -J<dedicated_kms_jce_jar_path> \
-genkeypair -alias <example-alias> -keyalg <algorithm> -keysize <key-size> -sigalg <signature-algorithm> \
-dname <example-distinguished-name> \
-keypass <example-password> -keystore <local-keystore-name> -storepass <example-password> -storetype DKKS 
-J-Djava.security.properties=<java_security_override_file>

Generate Secret Key

Use the -genseckey flag in the Key Management Utility with JCE .to perform this operation. This operation generates 1 secret key in the HSM.

To generate a secret key
Important

The secret key can't be found using an alias in the Key Management Utility. Before creating a secret key, sign in to the HSM and create a list of existing handles. You can use this list after creating the key pair to find the handle of the new secret key. See Identifying the Handle of a New Key Pair or Secret Key in the HSM for instructions.

Command syntax:

keytool \
-J-cp -J<dedicated_kms_jce_jar_path> \
-genseckey -alias <example-alias> -keyalg <algorithm> -keysize <key-size> \
-keypass <example-password> -keystore <local-keystore-name> -storepass <example-password> -storetype DKKS

Identifying the Handle of a New Key Pair or Secret Key in the HSM

New key pairs or secret keys created in the HSM cannot be found using an alias in the Key Management Utility. You can find the handle of a new key pair or secret key by comparing a list of all handles before a key pair or secret key is generated with a second list of all handles created after a key pair or secret key is generated. The difference between the two lists shows the newly created handle for the key pair or secret key.

To identify the handle of the new key
  1. Sign in to the HSM with the Key Management Utility.

  2. Run the following command to find and save a list of the existing handles:

    findKey -c <key-type>

    For the <key-type>, valid values are: 2 = public 3 = private 4 = secret. See Finding a Single Key for more information.

  3. Generate a key pair or secret key. See Generate Key Pair and Generate Secret Key for instructions.
  4. Repeat steps 1 and 2 and use the findKey -c 4 command to find and save a list of the handles in the HSM. The new list includes the handle for the newly generated key pair or secret key.
  5. Perform a diff operation on the two lists to find new handle.

Deleting a Key

Use the instructions in the following expandable section to delete keys from the local keystore and the HSM.

To delete a key

  1. Run the following keytool command to delete the key in the local keystore:

    keytool \
-J-cp -J<dedicated_kms_jce_jar_path> \
-delete -alias <example-alias> \
-keypass <example-password> -keystore <example-keystore-name> -storepass <example-password> -storetype DKKS

  2. To delete a key in the HSM, run the following command in the Dedicated Key Management utility:

    deleteKey -k <key-handle>

    See Deleting a Key for more information:

Generating a Certificate Signing Request (CSR) with Keytool

Use the -certreq flag to generate a certificate signing request (CSR) using a key in the HSM. The command is run using the keytool utility with JCE.

To generate a CSR

Run the following command to generate a CSR using a key in the HSM:

keytool \
-J-cp -J<dedicated_kms_jce_jar_path> \
-certreq \
-alias <example-alias> \
-file <csr-file> \
-keyalg -keyalg <algorithm> -keysize <key-size> -sigalg <signature-algorithm> \
-dname <example-distinguished-name> \
-keypass <example-password> -keystore <local-keystore-name> -storepass <example-password> -storetype DKKS

Importing a Cert Into a Keystore

Use the -importcert flag to import a cert into the local keystore. The command is run using the keytool with JCE.

To import a cert into a keystore

Command syntax:

keytool \
-J-cp -J<dedicated_kms_jce_jar_path> \
-importcert -noprompt \
-alias <example-alias> \
-file <crt-file> \
-keypass <example-password> -keystore <local-keystore-name> -storepass <example-password>

Importing a Java Keystore Into the HSM

Use the -importkeystore flag to import all keys in a keystore into the HSM. The command is run using keytool with JCE.

To import keystore into the HSM

Important:

  • When you use the keytool command to generate a key pair or import an existing keystore, your Java Security configuration ensures that a public and private key are generated in the HSM card. If you're using the java.security file for this configuration, the OCI Dedicated KMS provider must be specified as priority 2 in the file for key pairs to be generated in the HSM.

    Alternately, in the current directory, create a Java Security Override File file and add the OCI Dedicated KMS provider in the second position as security.provider.2. When executing a Keytool command, use the following option to specify the Java Security Override file:

    -J-Djava.security.properties=<java_security_override_file>

    See Add the JCE Provider to Java Security for more information on configuring Java Security.

  • If you import a keystore with 2 or more keys into the HSM, you can't identify the handle of the keys using the method described in Identifying the Handle of a New Key Pair or Secret Key in the HSM, and you can't reference the keys in the Key Management Utility using an alias.

Command syntax:

keytool \
-J-cp -J<dedicated_kms_jce_jar_path> \
-J-Djava.security.properties=<java_security_override_file> \
-importkeystore \
-srckeystore <example-source-keystore> - srcstoretype <example-source-keystore-type> -srcstorepass <example-source-keystore-password> \
-destkeystore <example-destination-keystore> -deststoretype DKKS - deststorepass <example-destination-keystore-password> \

Initializing a Keystore

If you don't have an empty initialized keystore, you can create one by performing the following operations:

  1. The keytool program can't create an empty DKKS keystore, but you can use keytool to create a keystore as part of a key generation operation. After you generate a key with keytool, you can delete the key, and the initialized keystore remains available to you.

    Use the instructions in Generate Key Pair and Identifying the Handle of a New Key Pair or Secret Key in the HSM to generate a key pair that can be identified by a handle. When you generate this key pair, the keytool utility creates an initialized keystore that you can use for future operations.

  2. Delete the unnecessary key pair from the HSM using the instructions in Deleting a Key.