Generating a certificate
Generating a certificate
If you do not have a certificate, follow the procedure in this article that corresponds to the certificate type you choose to generate.
Choose from the following certificate types:
Both certificate types are self-signed certificates.
Creating a PKCS12 keystore
Use can create PKCS12 certificates tht are stored in USS. This certificate is used for encrypting TLS communication between Zowe clients and Zowe z/OS servers, as well as intra z/OS Zowe server to server communcation. Zowe uses a keystore directory to contain its external certificate, and a truststore directory to hold the public keys of servers it communicate with (for example z/OSMF).
Follow these steps to generate a PKCS12 keystore:
Configure the PKCS12 setup section in zowe.yaml
To assist with updating zowe.yaml
, see the example yaml for scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates in the article Certificate configuration scenarios.
For PKCS12 certificate users, customize the following parameters in the zowe.yaml
file:
Parameter | Description |
---|---|
zowe.setup.certificate.pkcs12.directory | Specifies the directory where you plan to store the PKCS12 keystore and truststore. This is required if zowe.setup.certificate.type is PKCS12. |
zowe.setup.certificate.pkcs12.lock | Is a boolean configuration to tell if we should lock the PKCS12 keystore directory only for Zowe runtime user and group. Default value is true. |
zowe.setup.certificate.pkcs12 (Optional) | Defines name, password, caAlias and caPassword to customize the keystore and truststore. It is recommended to update these values from the default values. Note: Alias names should be all in lower case. |
dname (Optional) | Specifies the distinguished name. Domain names and IPs should be added into certificate SAN. If the field san is not defined, the zwe init command uses zowe.externalDomains . |
Configuring the zowe.yaml
file for a PKCS12 certificate
The following zowe.yaml
example generates the following artifacts:
- A
PKCS12
certificate, specified inzowe.setup.certificate.type
. - A keystore directory
/var/zowe/keystore
, specified inzowe.setup.certificate.pkcs12.directory
. - A certificate name (or alias)
localhost
, specified inzowe.setup.certificate.pkcs12.name
. - A certificate authority name
local_ca
, specified inzowe.setup.certificate.certificate.pkcs12.caAlias
.
Example zowe.yaml
using PKCS12:
zowe:
setup:
certificate:
type: PKCS12
pkcs12:
directory: /var/zowe/keystore
lock: true
name: localhost # Optional, default value is localhost.
password: password # Optional, default value is password.
caAlias: local_ca # Optional, default value is local_ca.
caPassword: local_ca_password # Optional, default value is local_ca_password.
dname: # Distinguished name for Zowe generated certificates. All optional.
caCommonName: ""
commonName: ""
orgUnit: ""
org: ""
locality: ""
state: ""
country: ""
validity: 3650
san:
- dvipa.my-company.com
- 12.34.56.78
To get the san IP address, run ping dvipa.my-company.com
in your terminal.
Run the command to generate a PKCS12 keystore
After you configure the zowe.yaml
, use the following procedure to generate the PKCS12 certificate.
-
Log in to your system. In this example, run
ssh dvipa.my-company.com
with your password. -
Run the following command in the directory with this
zowe.yaml
in the terminal to generate the certificate and update the configuration values in thezowe.yaml
file.zwe init certificate -c <path-to-your-zowe-configuration-yaml> --update-config
The following command output shows the generation of a PKCS12 keystore using the default values, and has the following associated artifacts. (Note that some detailed output messages have been omitted.)
- The CA is created.
- The keystore is created and the CA is added to the keystore.
- The certificate is created and is added to the keystore.
- The truststore is created.
- Directory permissions are changed to restrict access to the private key.
Command output:
#>zwe init certificate -c <path-to-your-zowe-configuration-yaml> --update-config
-------------------------------------------------------------------------------
>> Creating certificate authority "local_ca"
>> Certificate authority local_ca is created successfully.
-------------------------------------------------------------------------------
>> Export keystore /global/zowe/keystore/local_ca/local_ca.keystore.p12
>> Keystore /global/zowe/keystore/local_ca/local_ca.keystore.p12 is exported successfully.
-------------------------------------------------------------------------------
>> Creating certificate "localhost"
>> Certificate localhost is created successfully.
-------------------------------------------------------------------------------
>> Export keystore /global/zowe/keystore/localhost/localhost.keystore.p12
>> Keystore /global/zowe/keystore/localhost/localhost.keystore.p12 is exported successfully.-------------------------------------------------------------------------------
>> Export keystore /global/zowe/keystore/localhost/localhost.truststore.p12
>> Keystore /global/zowe/keystore/localhost/localhost.truststore.p12 is exported successfully.
-------------------------------------------------------------------------------
>> Lock keystore directory /global/zowe/keystore
>> Keystore directory /global/zowe/keystore is locked.
-------------------------------------------------------------------------------
>> Update certificate configuration to <path-to-your-zowe-configuration-yaml>
- update "zowe.certificate.keystore.type" with value: PKCS12
...
- update "zowe.certificate.pem.certificateAuthorities" with value: /global/zowe/keystore/local_ca/local_ca.cer
>> Zowe configuration is updated successfully.
#>
The zwe init certificate
command generates a certificate based on zowe.yaml
values in the zowe.setup.certificate
section. The certificate values used at runtime are referenced in the zowe.certificate
section in the zowe.yaml
file. The command zwe init certificate -c <path-to-your-zowe-configuration-yaml> --update-config
updates the runtime zowe.certificate
section to reference the generated certificate generated from the zowe.setup.certificate
.
- Open the
zowe.yaml
file to check the references to the newly generated certificate values as shown in the following code snippet:
Updated zowe.certificate
section in zowe.yaml
:
certificate:
keystore:
type: PKCS12
file: /var/zowe/keystore/localhost/localhost.keystore.p12
password: password
alias: localhost
truststore:
type: PKCS12
file: /var/zowe/keystore/localhost/localhost.truststore.p12
password: password
pem:
key: /var/zowe/keystore/localhost/localhost.key
certificate: /var/zowe/keystore/localhost/localhost.cer
certificateAuthorities: /var/zowe/keystore/local_ca/local_ca.cer
- (Optional) For details about the certificate you generated, run the following command:
keytool -v -list -keystore localhost.keystore.p12 -storetype PKCS12
You completed the procedure to generate a PKCS12 keystore.
For more information about additional commands to manage a keystore, see the keytool documentation.
Next steps after PKCS12 setup
When using a Zowe-generated certificate, you will be challenged by your browser when logging in to Zowe to accept Zowe's untrusted certificate authority. Depending on the browser you are using, there are different ways to proceed. See next steps about how to import the PKCS12 certificate to your browser.
Creating a JCERACFKS certificate
You can create a JCERACFKS certificate for use in a z/OS keystore. JCERACFKS uses SAF and RACF services to protect key material and certificates.
Use the following procedure to configure the zowe.yaml
file for JCERACFKS certificates:
- Configure the JCERACFKS setup section in zowe.yaml
- Run the command to generate a JCERACFKS certificate
To assist with updating zowe.yaml
, see the example yaml in Scenario 3: Use a z/OS keyring-based keystore with Zowe generated certificates in the article Certificate configuration scenarios.
Configure the JCERACFKS setup section in zowe.yaml
For JCERACFKS certificate (z/OS key ring) users, customize the following parameters in the zowe.yaml
file:
Parameter | Description |
---|---|
zowe.setup.certificate.keyring.owner | The key ring owner. This parameter is optional and the default value is zowe.setup.security.users.zowe . If this parameter is not defined, the default value is ZWESVUSR. |
zowe.setup.certificate.keyring.name | Specifies the key ring name to be created on z/OS. This parameter is required if zowe.setup.certificate.type is JCERACFKS . |
The following zowe.yaml
example generates the following artifacts:
- A
JCERACFKS
certificate, specified inzowe.setup.certificate.type
. - A key ring named
ZoweKeyring
specified inzowe.setup.certificate.keyring.name
. - A certificate with the label
localhost
specified inzowe.setup.certificate.keyring.label
. - A certificate authority with the label
localca
specified inzowe.setup.certificate.keyring.caLabel
with a common nameZowe Service CA
.
Example zowe.yaml
file using a JCERACFKS certificate:
zowe:
setup:
certificate:
type: JCERACFKS
createZosmfTrust: true
keyring:
name: ZoweKeyring
label: localhost # Optional, default value is localhost.
caLabel: localca # Optional, default value is localca.
dname: # Distinguished name for Zowe generated certificates. All optional.
caCommonName: ""
commonName: ""
orgUnit: ""
org: ""
locality: ""
state: ""
country: ""
validity: 3650
san:
- dvipa.my-company.com
- 12.34.56.78
- Alias names should be all lower cases.
- The name and lables shown above are the default value in
zowe.yaml
. dname
for distinguished name is all optional.- Domain names and IPs should be added to the certificate SAN. If the field
san
is not defined, thezwe init
command will usezowe.externalDomains
. The value for thesan
parameter presented in the example is for demonstration purposes.
Run the command to generate a JCERACFKS certificate
After you configure the zowe.yaml
, use the following procedure to generate a JCERACFKS certificate.
-
Log in to your system. In this example, run
ssh dvipa.my-company.com
with your password. -
Run the following command in the directory with this
zowe.yaml
in terminal to generate the certificate and update the configuration values inzowe.yaml
.zwe init certificate -c <path-to-your-zowe-configuration-yaml> --update-config
When the command is run, a customized JCL member name is created in the
CUST.JCLLIB
data set. The PDS name is defined in thezowe.setup.dataset.jcllib
property. In the following example output, the PDS memberUSER.ZWEV2.CUST.JCLLIB(ZW101431)
is created that contains the security manager commands, and then submitted as a job ID:ZWEKRING(JOB03054)
.
The following command output shows the generation of a JCERACFKS certificate using the default values. Note that some detailed output messages have been omitted.
Command output:
#>zwe init certificate -c <path-to-your-zowe-configuration-yaml> --update-config
-------------------------------------------------------------------------------
>> Generate Zowe certificate in keyring
>>>> Modify ZWEKRING
- IBMUSER.ZWEV2.CUST.JCLLIB(ZW101431) is prepared
>>>> Submit IBMUSER.ZWEV2.CUST.JCLLIB(ZW101431)
- Job ZWEKRING(JOB03054) ends with code 0 (COMPLETED).
>> Certificate is generated in keyring successfully.
-------------------------------------------------------------------------------
>> Update certificate configuration to <path-to-your-zowe-configuration-yaml>
>> Zowe configuration is updated successfully.
#>
As shown in the example, the job ends with code 0
. There may, however, be failures in the individual steps. It is advised to check the job output. The security manager commands in the job are generated based on the value of zowe.security.product
. Job steps for each product can be determined by the security manager.
- Open the
zowe.yaml
file to check the references to the newly generated certificate values. Because the--update-config
parameter was specified, the runtime configuration section of zowe.yaml is updated to match the values to the generated keystore, certificate, and certificate authority. The updated section is shown in the following code snippet:
Updated zowe.certificate
section in zowe.yaml
:
zowe:
certificate:
keystore:
alias: localhost
password: 'password'
file: safkeyring://ZWESVUSR/ZoweKeyring
type: JCERACFKS
truststore:
type: JCERACFKS
file: safkeyring://ZWESVUSR/ZoweKeyring
password: "password"
pem:
key:
certificate:
certificateAuthorities: safkeyring://ZWESVUSR/ZoweKeyring&localca
zowe.certificate.keystore.password
has a hardcoded password value. If you are using type: PKCS12
, the password field must be the real password.
You completed the procedure to generate a JCERACFKS certificate.
Next steps after JCERACFKS setup
For more information about how to use your JCERACFKS certificate, see Use JCERACFKS certificates.