Generating Keys and Aliases for Encryption on LTO Ultrium 4 and LTO Ultrium 5

Keytool is the preferred utility for managing keys, certificates, and aliases. It enables you to generate, import, and export your encryption data keys and store them in a keystore.

Each data key in the keystore is accessed through a unique alias. An alias is a string of characters, such as 123456tape. In JCEKS and most other keystores, 123456Tape would be equivalent to 123456tape and can access the same entry in the keystore. Check the documentation for your keystore type to determine whether it is case-sensitive. When you use the keytool -genseckey command to generate a data key, you specify a corresponding alias in the same command. The alias identifies the correct key in the correct key group and keystore. It is used in writing and reading encrypted data on LTO Ultrium 4 and LTO Ultrium 5 tape.

Note: Individual aliases and alias ranges must be unique. This requirement is enforced when keys are generated on a given keystore/Security Key Lifecycle Manager for z/OS instance. However, in a multiple Security Key Lifecycle Manager for z/OS or Keystore environment, you should use a naming convention. Use a naming convention that maintains uniqueness across multiple instances in the event it becomes necessary to transport keys between instances while maintaining uniqueness of reference.

After generating keys and aliases, update the symmetricKeySet property in the ISKLMConfig.properties.zos file to specify the new alias, range of aliases, or key group GroupID. You must also update the filename under which the symmetric keys are stored, and the filename where key groups are defined. See Creating and managing key groups for details. Only those keys named in the symmetricKeySet are validated (checked for an existing alias and a symmetric key of the proper size and algorithm). If an invalid key is specified in this property, the software does not start and an audit record is created.

The keytool utility also provides for the import and export of data keys to and from other keystores. An overview of each task follows. You can issue the keytool -help to show all the related parameters covered in the following discussions.

If you are not using Keytool

If you use a utility other than keytool to generate keys and aliases, you cannot generate ranges of keys compatible with the Security Key Lifecycle Manager for z/OS. To generate individual keys compatible with the Security Key Lifecycle Manager for z/OS, be sure to specify aliases using one of the following formats:

12 printable characters or less (for example, abcdefghijk)
3 printable characters, followed by two zeros, followed by 16 hexadecimal digits (for example, ABC000000000000000001) for a total of exactly 21 characters

Generating data keys and aliases using Keytool -genseckey

The Keytool utility generates aliases and symmetric keys for encryption on LTO Ultrium 4 and LTO Ultrium 5 Tape Drives using LTO Ultrium 4 and LTO Ultrium 5 tape. Use the keytool -genseckey command to generate one or more secret keys and store them in a specified keystore. keytool -genseckey takes the following parameters:

-genseckey   [-v] [-protected]
             [-alias <alias> | aliasrange <aliasRange>] [-keypass <keypass>]
             [-keyalg <keyalg>] [-keysize <keysize>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <storetype>] [-providerName <name>]
             [-providerPath <pathlist>]

These parameters are important when generating data keys for Security Key Lifecycle Manager for z/OS to serve to the LTO Ultrium 4 and LTO Ultrium 5 drives for tape encryption:

-alias: Specify an alias value for a single data key with up to 12 printable characters (for example, abcfrg or key123tape).
-aliasrange: When generating multiple data keys, aliasrange is specified as a 3-character alphabetic prefix. It is followed by lower and upper limits for a series of 16-character (hexadecimal) strings with leading zeroes filledin automatically to construct aliases 21-characters in length. For example, specifying key1-a would yield a series of aliases from KEY000000000000000001 through KEY00000000000000000A. Specifying an aliasrange value of xyz01-FF would yield XYZ000000000000000001 through XYZ0000000000000000FF, which would generate 255 symmetric keys.
-keypass: Specifies a password used to protect the data key. This password must be identical to the keystore password. If no password is specified, you are prompted for it. If you press Enter at the prompt, the key password is set to the same password used for the keystore. keypass must be at least six characters long.
Note: When you have set the keystore password, do not change it unless its security has been breached. See Changing Keystore Passwords.
-keyalg: Specifies the algorithm to be used to generate the data key. If the encrypted tape is shared with systems on the z/OS® platform and the zOSCompatibility property is set to true, the key algorithm should be specified as DESede. This setting ensures compatibility.
-keysize: Specifies the size of the data key to be generated. The key size must be specified as 256. If -keyalg is specified as DESede for z/OS compatibility, then -keysize must be allowed to default to 168.

Examples of acceptable aliases that can be associated with symmetric keys are:

abc000000000000000001
abc00a0120fa000000001

Examples of aliases that would not be accepted are:

abcefghij1234567 ? wrong length
abcg0000000000000001 ? prefix is longer than 3 characters

If an alias exists in the keystore, keytool throws an exception and stops.

Changing Keystore Passwords

Note: When you have set the keystore password, do not change it unless its security has been breached. The passwords are obfuscated to eliminate any security exposure. This command will change both the keystore password and all of the aliases in the keystore with one command:

keytool -keystore <keystorename>  -storetype <keystoretype>
-keypasswd -new <newpassword> -all -storepasswd -new <newpassword>

Note: The value for both -new keywords MUST be identical.

You must also edit ISKLMConfig.properties.zos to change the keystore password in every server configuration file property where it is specified using one of these methods:

Delete the entire obfuscated password and type the new password in the clear. This refers to the non-obfuscated property. For example, config.keystore.password. It will be obfuscated on the next startup.
Delete the entire obfuscated password and set the Security Key Lifecycle Manager for z/OS to prompt on the next startup.

Importing data keys using Keytool -importseckey

Use the keytool -importseckey command to import a secret key or a batch of secret keys from an import file. keytool -importseckey takes the following parameters:

-importseckey       [-v]
             [-keyalias <keyalias>] [-keypass <keypass>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <storetype>] [-providerName <name>]
             [-importfile <importfile>]

These parameters are important when importing data keys for the Security Key Lifecycle Manager for z/OS to serve to the LTO Ultrium 4 and LTO Ultrium 5 drives for tape encryption:

-keyalias: Specifies the alias of a private key in keystore to decrypt all the data keys in importfile.
-importfile: Specifies the file that contains the data keys to be imported.

Exporting data keys using keytool -exportseckey

Use the keytool -exportseckey command to export a secret key or a batch of secret keys to an export file. keytool -exportseckey takes the following parameters:

-exportseckey      [-v]
             [-alias <alias> | aliasrange <aliasRange>] [-keyalias <keyalias>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <storetype>] [-providerName <name>]
             [-exportfile <exportfile>]

These parameters are important when exporting data keys for Security Key Lifecycle Manager for z/OS to serve to the LTO Ultrium 4 and LTO Ultrium 5 drives for tape encryption:

-alias: Specify an alias value for a single data key with up to 12 printable characters (for example, abcfrg or key123tape).
-aliasrange: When exporting multiple data keys, aliasrange is specified as a 3-character alphabetic prefix. It is then followed by lower and upper limits for a series of 16-character (hexadecimal) strings with leading zeroes filled-in automatically to construct aliases 21-characters in length. For example, specifying key1-a would yield a series of aliases from KEY000000000000000001 through KEY00000000000000000A. Specifying an aliasrange value of xyz01-FF would yield XYZ000000000000000001 through XYZ0000000000000000FF
-exportfile: Specifies the file to store the data keys when they are exported.
-keyalias: Specifies the alias of a public key in keystore to encrypt all the data keys. Ensure that the keystore where the symmetric (data) keys are, contains the corresponding private key.

Sample alias and symmetric key setup for LTO Ultrium 4 and LTO Ultrium 5 encryption using a JCEKS keystore

Invoke the KeyTool with the -aliasrange option.

If the encrypted tape is shared with systems on the z/OS platform and zOSCompatibility property is set to true, then key algorithm (-keyalg) must be specified as: DESede.

keytool –genseckey –v –aliasrange AES01-FF –keyalg DESede  
–keypass password -storetype jceks –keystore path/filename.jceks

These KeyTool invocations generate 255 sequential aliases in the range AES000000000000000001 through AES0000000000000000FF and associated AES 256-bit symmetric keys. Either can be repeated cumulatively. It can be done as many times as necessary to setup the full number of ranged and stand-alone key aliases that are needed for robust operation. For example, to generate an additional alias and symmetric key for LTO Ultrium 4 and LTO Ultrium 5:

$JAVA_HOME/bin/keytool –genseckey –v –alias abcfrg –keyalg AES –keysize 256
–keypass password -storetype jceks –keystore path/filename.jceks

This invocation adds stand-alone alias abcfrg cumulatively. It is added to the named keystore which already contains 255 aliases from the invocation above yielding 256 symmetric keys in the JCEKS file named in –keystore option.

Update the symmetricKeySet property in the ISKLMConfig.properties.zos file. Add the following line to match any or all of the alias ranges used above, and the filename under which the symmetric keys were stored. The Security Key Lifecycle Manager for z/OS cannot start if an invalid alias is specified. Other causes for validation check failure can include incorrect bit size (for AES keysize must be 256) or an invalid algorithm for the platform. The file name specified in the config.keystore.file must match the name specified in the –keystore <filename> in the KeyTool invocation:

symmetricKeySet = AES01-FF,abcfrg
config.keystore.file = <filename>.jceks

Only those keys named in the symmetricKeySet is checked for an existing alias and a symmetric key of the proper size and algorithm. If an invalid key is specified in this property, the Security Key Lifecycle Manager for z/OS cannot start and an audit record is created.