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.
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.
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
securityUtility
command:- help
- Prints help information for a specified task.
- 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
, andhash
. The default value isxor
.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 thequickStartSecurity
element.When FIPS 140-3 is enabled, both the
aes
andhash
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 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.See also information about setting the variable for
wlp.password.encryption.key
. - --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.
- Certificate details:
- type: Self-signed certificate.
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 ofPKCS12
.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
oraes
. If this option is not provided, a default value ofxor
is used. - --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. TheCN
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.
- --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.
- 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
andaes
. If this option isn’t specified, a default encoding type ofxor
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 Open Liberty server for which the LTPA keys are created. This option
can’t be used if the
--file
option is specified.
Usage
The following examples demonstrate correct syntax:
securityUtility encode --encoding=aes GiveMeLiberty
securityUtility createSSLCertificate --server=myserver --password=mypassword --validity=365
--subject=CN=mycompany,O=myOrg,C=myCountry
securityUtility help createSSLCertificate
securityUtility createLTPAKeys --password=mypassword