Customize the KeyStore creation variables and invoke the KeyStore creation script

To create the KeyStore file and signed server certificate for RSE API, customize and submit the sample HUHCRYPT JCL, or customize the sample rseapi.certificate.env file and execute the huhcrypto.sh script. For the details on file location, see Select the KeyStore creation method.

Note: Only single word values are supported. Blanks ( ), single quotation marks (‘), or double quotation marks (“) are not allowed.

Figure 1. rseapi.certificate.env

#Scenario
RSEAPI_CRYPTO_SCENARIO=1

# configuration directory
RSEAPI_CRYPTO_CONFIG=/etc/zexpl/rseapi_crypto

# started task user id
RSEAPI_CRYPTO_STC_USERID=STCAPI

# server keystore
RSEAPI_CRYPTO_ALIAS_SERVER=rseapiServer
RSEAPI_CRYPTO_KEYSTOREFILE_SERVER=${RSEAPI_CRYPTO_CONFIG}/keystore
RSEAPI_CRYPTO_STORETYPE_SERVER=JKS
RSEAPI_CRYPTO_STOREPASSWORD_SERVER=
RSEAPI_CRYPTO_COMMONNAME_SERVER=
RSEAPI_CRYPTO_ORGANIZATIONUNIT=
RSEAPI_CRYPTO_ORGANIZATION=
RSEAPI_CRYPTO_LOCALE=
RSEAPI_CRYPTO_STATE=
RSEAPI_CRYPTO_COUNTRY=
RSEAPI_CRYPTO_VALIDITY_SERVER=365
RSEAPI_CRYPTO_SIGNEDCSR_SERVER=

# certificate authority
RSEAPI_CRYPTO_PUBLIC_CER_CA=
RSEAPI_CRYPTO_ALIAS_CA=${RSEAPI_CRYPTO_ALIAS_SERVER}.CA
RSEAPI_CRYPTO_KEYSTOREFILE_CA=${RSEAPI_CRYPTO_KEYSTOREFILE_SERVER}.CA
RSEAPI_CRYPTO_STORETYPE_CA=$RSEAPI_CRYPTO_STORETYPE_SERVER
RSEAPI_CRYPTO_STOREPASSWORD_CA=$RSEAPI_CRYPTO_STOREPASSWORD_SERVER
RSEAPI_CRYPTO_KEYPASSWORD_CA=$RSEAPI_CRYPTO_STOREPASSWORD_CA
RSEAPI_CRYPTO_COMMONNAME_CA=rseapi_local_ca
RSEAPI_CRYPTO_VALIDITY_CA=$RSEAPI_CRYPTO_VALIDITY_SERVER

The following terms are used in describing the variables:

${…}: A reference to the value of the variable whose name is inside the braces.
Certificate Authority (CA): A trusted party that signs the server certificate and vouches that the server that presents the certificate is the RSE API server.
Certificate: An electronic document that holds the public key of a private/public key pair. The issuer of the certificate holds the private key. You can use a server certificate to identify the RSE API server. You can use a CA certificate to identify the CA that signed the server certificate.
Certificate Signing Request (CSR): An electronic document that is sent to a CA to request that the CA signs the embedded server certificate.
Java Key Store (JKS): A standard for KeyStore layout.
KeyStore: A secure file that stores one or more certificates, with or without their matching private key.

The following definitions are available:

RSEAPI_CRYPTO_SCENARIO

Indicate which scenario the huhsetup.sh script must perform. Valid values are 1, 2, 3a, or 3b. The default is 1.

Scenario 1 is to create a server certificate that is signed by a newly generated CA.
Scenario 2 is to create a server certificate that is signed by an existing CA owned by your organization.
Scenario 3 is split into multiple steps:
1. Specify 3a to create a CSR for a server certificate that is newly generated.
2. Ask a trusted CA to sign the CSR, and store the signed CSR on the host.
3. Run the script again when you are specifying 3b to import the CA certificate and signed CSR into the server KeyStore file.

RSEAPI_CRYPTO_CONFIG

The directory where the KeyStore file and exported certificates are placed. The default is /etc/zexpl/rseapi_crypto.

RSEAPI_CRYPTO_ STC_USERID

The user ID of the RSEAPI started task. The default is STCAPI. For more information, see Security Definitions.

Note: For the encrypted communication setup to complete successfully, this user ID must exist.

RSEAPI_CRYPTO_ALIAS_SERVER

The alias of the server certificate inside the server KeyStore file. The default is rseapiServer.

RSEAPI_CRYPTO_KEYSTOREFILE_SERVER

The complete path of the server KeyStore file. The default is ${RSEAPI_CRYPTO_CONFIG}/keystore.

RSEAPI_CRYPTO_STORETYPE_SERVER

The server KeyStore type. The default is JKS. Valid values are JKS and PKCS12.

RSEAPI_CRYPTO_STOREPASSWORD_SERVER

The password of the server KeyStore file. There is no default value.

Note: This variable is mandatory. If no value is specified, the KeyStore creation fails.

RSEAPI_CRYPTO_COMMONNAME_SERVER

The domain name or IP address of the RSE API server. There is no default.

Note:

This variable is mandatory. If no value is specified, the KeyStore creation fails.
If another name is used, the web browsers that connect to the RSE API server issue a warning.

RSEAPI_CRYPTO_SAN_SERVER

List of one or more alternate domain names for the server (SAN, Subject Alternate Name). There is no default. Uncomment and change to define alternate names. When used, the following syntax rules apply:

Multiple values must be separated by a comma (,).
Each value must start with “dsn:”, followed by the desired domain name.

RSEAPI_CRYPTO_ORGANIZATIONUNIT

The department inside your organization that owns the RSE API server. The default is SYSTEMS.

RSEAPI_CRYPTO_ORGANIZATION

The name of your organization. The default is IBM.

RSEAPI_CRYPTO_LOCALE

The city where your organization is located. The default is ARMONK.

RSEAPI_CRYPTO_STATE

The state or province where your organization is located. The default is NY.

RSEAPI_CRYPTO_COUNTRY

The country where your organization is located. The default is US. Specify the country in two-letter form.

RSEAPI_CRYPTO_VALIDITY_SERVER

The expiry of the server certificate in days. The default is 365. Valid values are positive whole numbers.

RSEAPI_CRYPTO_SIGNEDCSR_SERVER

The complete path of the signed CSR. The default is ${RSEAPI_CRYPTO_CONFIG}/signedcsr.cer. When RSEAPI_CRYPTO_SCENARIO equals 3b, ensure that this variable references the CSR that is signed and returned by the CA. This variable is either not used or used internally in other scenarios. Therefore, it's better to keep its default value.

RSEAPI_CRYPTO_PUBLIC_CER_CA

The complete path of the file that holds the CA certificate identifying the CA that signed the CSR. The default is ${RSEAPI_CRYPTO_CONFIG}/publicCA.cer. When RSEAPI_CRYPTO_SCENARIO equals 1, this file is created by the script. This file is mandatory input when RSEAPI_CRYPTO_SCENARIO equals 2 or 3b.

Note: Provide this file to your users so they can import it as the trusted CA in their browser, which avoids browser security warnings when they connect to the RSE API server.

RSEAPI_CRYPTO_ALIAS_CA

The alias of the CA certificate inside the CA KeyStore. The default is


${RSEAPI_CRYPTO_ALIAS_SERVER}.CA

. When RSEAPI_CRYPTO_SCENARIO equals 2, ensure that this variable holds a value valid for the CA KeyStore that you want to use for signing. This variable is either not used or used internally in other scenarios. Therefore, it's better to keep its default value.

RSEAPI_CRYPTO_KEYSTOREFILE_CA

The complete path of the CA KeyStore. The default is ${RSEAPI_CRYPTO_KEYSTOREFILE_SERVER}.CA. When RSEAPI_CRYPTO_SCENARIO equals 2, ensure that this variable holds a value valid for the CA KeyStore that you want to use for signing. This variable is either not used or used internally in other scenarios. Therefore, it's better to keep its default value.

RSEAPI_CRYPTO_STORETYPE_CA

The CA KeyStore type. The default is ${RSEAPI_CRYPTO_STORETYPE_SERVER}. When RSEAPI_CRYPTO_SCENARIO equals 2, ensure that this variable holds a value valid for the CA KeyStore that you want to use for signing. This variable is either not used or used internally in other scenarios. Therefore, it's better to keep its default value.

RSEAPI_CRYPTO_STOREPASSWORD_CA

The password of the CA KeyStore. The default is ${RSEAPI_CRYPTO_STOREPASSWORD_SERVER}. When RSEAPI_CRYPTO_SCENARIO equals 2, ensure that this variable holds a value valid for the CA KeyStore that you want to use for signing. This variable is either not used or used internally in other scenarios. Therefore, it's better to keep its default value.

RSEAPI_CRYPTO_KEYPASSWORD_CA

The password of the CA private key inside CA KeyStore. The default is ${RSEAPI_CRYPTO_STOREPASSWORD_CA}. When RSEAPI_CRYPTO_SCENARIO equals 2, ensure that this variable holds a value valid for the CA KeyStore that you want to use for signing. This variable is either not used or used internally in other scenarios. Therefore, it's better to keep its default value.

RSEAPI_CRYPTO_COMMONNAME_CA

The common name of the self-generated CA. The default is rseapi_local_ca. This variable is used only when RSEAPI_CRYPTO_SCENARIO equals 1.

RSEAPI_CRYPTO_VALIDITY_CA

The expiry of the CA certificate in days. The default is ${RSEAPI_CRYPTO_VALIDITY_SERVER}. Valid values are positive whole numbers.