securityUtility command

The securityUtility command supports plain text encryption, SSL certificate creation, and creating LTPA keys for Liberty.

Documentation for the securityUtility command in version 21.0.0.11 and later is available on the Open Liberty website.

Syntax

The command syntax is as follows:

securityUtility task [options]

Where the options are different based on the value of task.

CAUTION:

Different operating systems and command line environments treat some characters differently. In many environments, you can redefine which characters are special and how they behave.

By default, in the Windows environment, if you have an exclamation point (!) in your input string, it must be escaped by the caret character (^). The following example has a value of a! encoded.

D:\Liberty\images\855\Liberty855\wlp\bin>securityUtility encode "a^!"

For some operating systems, you might need to use single quotation marks around arguments that are passed to the tool.

If you use a terminal emulator, make sure that your session is configured to use the same code page as your server.

Refer to your operating system, command shell, and terminal emulator documentation about special characters and code pages if you experience unexpected results.

Parameters

The following tasks are available for the securityUtility command:

help: Prints help information for a specified task.

generateAESKey

Generates a Base64-encoded AES-256 key for password encryption. The generated key can be used by defining the wlp.aes.encryption.key variable in a Liberty configuration file.

The options are:

--createConfigFile=name: Creates an XML configuration file that contains the generated AES key in the wlp.aes.encryption.key variable. If this option is not provided, the key is printed to the console.
--key=password: Derives a Base64-encoded AES-256 key from the provided passphrase by using Liberty's internal key-derivation function. If this option is not specified, a random AES-256 key is generated.

encode

Encodes the provided text by using Base64. If no options are specified, the command enters interactive mode. Otherwise, the provided text is encoded. Text with spaces must be put in quotation marks.

The options are:

--encoding=encoding_type

Specifies how to encode the password. Supported encodings are xor, aes, and hash. The default value is xor.

[25.0.0.2 and later] The aes type uses AES-256 encryption.

In version 25.0.0.1 and earlier, the aes type uses AES-128 encryption.

You can use the hash encoding option to encode passwords for the basic user registry and the quickStartSecurity element.

[25.0.0.3 and later] When FIPS 140-3 is enabled, both the aes and hash options use enhanced algorithms to encrypt and encode strings. Strings that were encrypted or encoded with these options before the algorithms were enhanced might fail in FIPS 140-3 environments.

--key=encryption_key

Specifies the key to be used when you encode by using AES encryption. This string is hashed to produce the AES encryption key that is used to encrypt and decrypt the password. The key can be provided to the server by defining the variable wlp.password.encryption.key whose value is the key. If this option is not provided, a default key is used.

See also information about setting the variable for wlp.password.encryption.key.

--base64Key=base64_key

Specifies a Base64-encoded AES-256 key to encode the password by using AES encryption. The key can be provided to the server by defining the wlp.aes.encryption.key variable. This option cannot be used with the --aesConfigFile or --key options.

--aesConfigFile=file

Specifies an XML or Java properties file that defines either the wlp.password.encryption.key or wlp.aes.encryption.key variable. Both variables cannot be present in the same file. This option cannot be used with the --base64Key or --key options.

--listCustom

Display the information of the custom password encryption in JavaScript Object Notation (JSON) format. The information consists of:

name: The custom password encryption algorithm name.
featurename: The feature name.
description: The description of the custom password encryption.

For more information about custom password encryption, see Developing a customPasswordEncryption Provider.

--notrim

Specify whether space characters are removed from the beginning and end of the specified text. If this option is specified, the provided text is encoded as it is. If this option is not specified, space characters from the beginning and end of the specified text are removed.

text

The text that is to be encoded.

createSSLCertificate

Creates a default keystore that includes an SSL certificate for use in a server or client configuration.

Keystore details:: location: In the resource/security/key.p12 file of the server or client directory.; type: PKCS12; In version 19.0.0.2 and earlier: location: In the resource/security/key.jks file of the server or client directory.; In version 19.0.0.2 and earlier: type: JKS; password: Password that is provided with the --password option. The password is needed to open the keystore file and retrieve the key from the keystore file.
Certificate details:: type: Self-signed certificate.; size: 2048 by default, an alternative size can be specified with the --keySize option.; signature algorithm: SHA256withRSA, can be customized with the --sigAlg option.; validity: 365 days by default, can be customized with the --validity option.; SubjectDN: CN=<hostname>,OU=<client or server name>,O=ibm,C=us by default, can be customized with the --subject option.

The options are:

--server=name

Specifies the name of the Liberty server for which the keystore and certificate is created. This option cannot be used if the --client option is specified.

--client=name

Specifies the name of the Liberty client for which the keystore and certificate is created. This option cannot be used if the --server option is specified.

--keyType=keystore type

Specifies the keystore type to generate. To generate a JKS keystore, specify the --keyType option with the value of JKS. By default, a PKCS12 keystore is generated. However, to explicitly specify the generation of a PKCS12 keystore, specify the --keyType option with the value of PKCS12.

A PKCS12 keystore has a number of advantages over a JKS keystore. The PKCS12 keystore is more extensible, supports stronger cryptographic algorithms, and is widely adopted. The PKCS12 format is frequently the format that certificate authorities provide when they issue certificates.

--keySize=size

Specifies the certificate key bit size. The default value is 2048.

--password=password

Specifies the password to be used in the keystore, which must be at least six characters in length. This option is required.

--passwordEncoding=password_encoding_type

Specifies how to encode the keystore password. Supported encoding value is xor or aes. If this option is not provided, a default value of xor is used.

[25.0.0.2 and later] The aes type uses AES-256 encryption.

In version 25.0.0.1 and earlier, the aes type uses AES-128 encryption.

--passwordKey=password_encryption_key

Specifies the key to use to encode the keystore password by using AES encryption. This string is hashed to produce an encryption key that is used to encrypt and decrypt the password. The key can be provided to the server by defining the variable wlp.password.encryption.key whose value is the key. If this option is not provided, a default key is used.

--validity=days

Specifies the number of days that the certificate is valid, which must be equal to or greater than 365. If this option is not provided, a default value of 365 is used.

--subject=DN

Specifies the Distinguished Name (DN) for the certificate subject and issuer. If this option is not provided, a default value of

CN=<hostname>,OU=<server or client
name>,O=ibm,C=us

is used. The CN value is retrieved by using a java method to get the machine's local hostname. If the hostname cannot be resolved, the IP address is returned.

--sigAlg

Specifies the signature algorithm that is used to sign the self-signed certificate. The signature algorithm that is supported depends on what is supported by the underlying JRE. Stronger signature algorithms might require the JRE to have the unrestricted policy file in place.

The command accepts SHA256withRSA (default), SHA1withRSA, SHA384withRSA, SHA512withRSA, SHA1withECDSA, SHA256withECDSA, SHA384withECDSA, and SHA512withECDSA. The signature algorithms that end with RSA creates certificates with RSA keys and the signature algorithms that end with ECDSA creates certificates with Elliptical Curve (EC) keys.

Note: If you are using certificates that are created with EC keys, then your server needs a customized ciphers list in the ssl configuration to include EC ciphers.

--extInfo

Specifies any X.509 certificate extension information that it uses to create the default certificate. By default, the Subject Alternative Name extension is added to the certificate with the host name of the server. If the --extInfo option is used, the value is passed directly to the keytool command. Use the syntax of the --ext flag on the keytool command.

--passwordBase64Key=base64_key

Specifies a Base64-encoded AES-256 key that is used to encrypt the keystore password when the --passwordEncoding=aes option is specified. This option cannot be used with the --aesConfigFile or --passwordKey options.

--aesConfigFile=file

Specifies an XML or Java properties file that defines the AES key to use for password encryption. The file must contain either the wlp.password.encryption.key or wlp.aes.encryption.key variable. This option cannot be used with the --passwordBase64Key or --passwordKey options.

createLTPAKeys

Creates a set of LTPA keys for use by the server, or that can be shared with multiple servers. If no server or file is specified, an ltpa.keys file is created in the current working directory.

The options are:

--file=name: The file in which to write the LTPA keys. This option can’t be used if the --server option is specified.
--passwordEncoding=password_encoding_type: Specifies how to encode the LTPA keys password in the server.xml file. Supported encoding types are xor and aes. If this option isn’t specified, a default encoding type of xor is used.
You can use the securityUtility encode --listCustom command to see if any additional custom encryptions are supported.
--passwordKey=password_encryption_key: Specifies the key to use to encode an LTPA keys password with AES encryption. This string is hashed to produce an encryption key that is used to encrypt and decrypt the password. You can provide the key by defining the wlp.password.encryption.key variable as the key value. If this option isn’t specified, a default key is used.
--server=name: Specifies the name of the Liberty server for which the LTPA keys are created. This option can’t be used if the --file option is specified.
--passwordBase64Key=base64_key: Specifies a Base64-encoded AES-256 key for encrypting the LTPA keys password when the --passwordEncoding=aes option is used. This option cannot be used with the --aesConfigFile or --passwordKey options.
--aesConfigFile=file: Specifies an XML or Java properties file that defines the AES key that is used to encode the LTPA keys password. The file must contain either wlp.password.encryption.key or wlp.aes.encryption.key. This option cannot be used with the --passwordBase64Key or --passwordKey options.

When FIPS 140-3 is enabled, LTPA keys must be created with FIPS 140-3 approved algorithms. To create LTPA keys that use FIPS 140-3 approved algorithms, export the following system property before you run the createLTPAKeys command:

export JVM_ARGS="-Xenablefips140-3 -Dcom.ibm.jsse2.usefipsprovider=true -Dcom.ibm.jsse2.usefipsProviderName=IBMJCEPlusFIPS"

After the system properties are set, replace the existing LTPA keys with the newly created LTPA keys. For more information, see Setting up Liberty for FIPS compliance.

configureFIPS

Configures FIPS 140-3 across all servers and clients.

The options are:

--server=server_name

Configures FIPS 140-3 at a specified server.

--client=client_name

Configures FIPS 140-3 at a specified client.

--customProfileFile=name

For IBM Semeru Runtime, creates a custom profile file with a specified name or at a specified location. The default name of the custom profile file is FIPS140-3-Liberty-Application.properties.

If this option is not provided, the custom profile file is located in the /etc directory of your Liberty installation.
If this option is not provided and the --server option is used, the custom profile file is located in the /security directory of the specified server.
If this option is not provided and the --client option is used, the custom profile file is located in the /security directory of the specified client.

--disable

Disables FIPS 140-3 from all servers and clients that were not individually configured. Use the --server and --client options with the --disable option to disable FIPS 140-3 from specified servers and clients respectively.

Usage

The following examples demonstrate correct syntax:

securityUtility encode --encoding=aes --base64Key=<your_base64_key> GiveMeLiberty

securityUtility createSSLCertificate --password=<your_password> \
                                     --passwordEncoding=aes \
                                     --passwordBase64Key=<your_base64_key> \
                                     --server=myserver \
                                     --validity=365 \
                                     --subject=CN=mycompany,O=myOrg,C=myCountry

securityUtility createLTPAKeys --password=<your_password> \
                               --passwordEncoding=aes \
                               --passwordBase64Key=<your_base64_key> \
                               --file=myLTPA.keys

securityUtility help createSSLCertificate