You can create Secure Sockets Layer (SSL) digital certificates
and System Authorization Facility (SAF) keyrings that applications
can use to initiate HTTPS requests.
About this task
The owner of the SAF keyring (and personal keys) must be
the MVS™ user ID established by the servant region's
STARTED class profile. This user ID must be the owner because these
applications run in the WebSphere® Application Server
for z/OS® servant region address. This user ID is
different than the WebSphere Application Server
for z/OS controller user ID.
If you use keystores
and trust stores in a Hierarchical File System (HFS), a file name
uniquely identifies the file within the file system.
Procedure
- If you are using Resource Access Control Facility (RACF®)
as your security server, you can generate a personal keyring to be
used by your HTTPS application by specifying:
RACDCERT ID(ASSR1) GENCERT SUBJECTSDN(CN('J2EE SERVER') O('Z/OS WEBSPHERE')
L('POUGHKEEPSIE') SP('NEW YORK') C('US')) SIZE(512)
WITHLABEL('ASSR1 SERVER CERTIFICATE') SIGNWITH(CERTAUTH LABEL('PVT CA'))
In this example, the certificate authority used to
generate the unique servant region certificate is the same one used
to generate the certificates for the WebSphere Application
Server for z/OS servers by the customization job.
- Create a keyring with the same name used for the control
region user ID:
RACDCERT ADDRING(S1GRING) ID( ASSR1 )
The
new keyring is owned by the servant user ID for the certificate authority
certificate and the servant server certificate.
- You must have a certificate authority certificate (a certificate
from a certificate authority). You might choose to use the same certificate
authority to generate a certificate used by HTTPS applications, which
is similar to the certificate used for WebSphere Application
Server runtime processing. The certificate authority certificate that
is used to create the digital certificates is used by the WebSphere Application Server Runtime, and
is created during system customization (and can be created by the WebSphere z/OS Profile
Management Tool or the zpmt command). You can connect this
certificate authority certificate to the keyring you just created
by specifying:
RACDCERT ID(ASSR1) CONNECT (RING(S1GRING) LABEL('PVT CA') CERTAUTH)
For
this example: - S1GRING represents the RACF keyring
- ASSR1 represents the servant user ID
- PVT CA represents the certificate authority
Note that if the target of the request is another WebSphere Application Server for z/OS server,
you must also import the certificate authority certificate used by
the WebSphere Application Server for z/OS HTTPS
repertoire (which is generally set up during customization) into your
keyring if it is different than the certificate signer. If authentication
using client certificates is requested, you must also import the certificate
authority of your application into the HTTPS repertoire.
- Connect the personal certificate to your keyring:
RACDCERT ID(ASSR1) CONNECT(ID(ASSR1) LABEL('ASSR1 SERVER CERTIFICATE') RING(S1GRING) DEFAULT)
For
this example: - S1GRING represents the RACF keyring
- ASSR1 represents the servant user ID
- ASSR1 SERVER CERTIFICATE represents the server certificate
for servant user ID
- Enter the customizable information that needs to be unique
across a sysplex. This can include the:
- Subject's public key
- Subject's Distinguished Name (which uniquely identifies an entity
in an X.509 certificate)
- Common Name
- Title
- Organization name
- Organizational Unit name
- Locality name
- State or Province name
- Country
- Distinguished Name of the certificate authority that is issuing
the certificate
- Date from which the certificate is valid
- Expiration date of the certificate
- Version number
- Serial number
- Verify the output of your customization jobs to see what
is set up. Look at HLQ.DATA.(BBOWBRAK, BBOSBRAK if they
were saved), and record the settings of the certificate authority
certificate label, the servant region's started task identity. If
you wish to use an existing repertoire definition for web services,
the keyring name created.
Results
Note: Consider that:
- The repertoire type that is pointed to by the SSLConfig definition
must be a Java Secure Socket Extension (JSSE)
repertoire. This repertoire can be configured to refer to:
- Java Key Store (JKS) key store and trust store
files in an HFS file
- SAF keyrings such as RACFJSSESettings
- The scope of the repertoire definition depends upon the type of
repertoire. For example:
- When the repertoire refers to a SAF keyring, the keyring must
be owned by the MVS user ID of process that uses it. The customization
jobs create keyrings that are owned by the WebSphere Application
Server for z/OS controller started task user ID. WebSphere Application Server web services
clients run using the user ID of the WebSphere Application
Server for z/OS servant region's started task user ID.
This means that you must create a new keyring to be owned by the servant
region's user ID. This user ID is used by WebSphere Application
Server web services clients even if you specify an existing SSL repertoire.
- When the repertoire refers to an HFS file, all processes can share
the key stores. If you use key stores and trust stores in an HFS,
a file name uniquely identifies the file within the file system.
Some digital certificate and keyring management
is required to edit and use the sslConfig property, which
is one of the user-definable ibm-webservicesclient-bnd.xmi assembly
properties. .