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 customization dialogs). 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. For more information on the sslConfig property,
refer to ibm-webservicesclient-bnd.xmi
assembly properties.