®

IBM Software Group

WebSphere Partner Gateway (WPG)

Security - Certificate Management

MICHAEL GLENN
Level 2 Support
WebSphere Partner Gateway

WebSphere® Support Technical Exchange

 IBM Software Group

Agenda
 Creating Certificates With Ikeyman
 Exporting/Importing/Extracting Certificates With Ikeyman
 Managing Certificates Prior To Version 6.1.1
 Changes In Certificate Management in Version 6.1.1 and Later
 Certificate Load Wizard
 Troubleshooting
 Useful Links
 Summary
 References
 Questions and Answers

WebSphere ® Support Technical Exchange 2 of 53

 ®

IBM Software Group

Creating Certificates With Ikeyman

WebSphere® Support Technical Exchange

 IBM Software Group

Managing Certificates with Ikeyman

Ikeyman utility can be used
to manage certificates:
Create Self-Signed
Certificates
Import/Export
Certificates
Add/Delete Certificates
Etc…

WebSphere ® Support Technical Exchange 4 of 53

 IBM Software Group

Creating PKCS12 Keystore

 Step1: Create a new keystore
Click on Key Database File
Click on New
Select PKCS12 for Key
Database type
Choose filename and
location
Press OK
Enter Password for
KeyStore and Press Ok

WebSphere ® Support Technical Exchange 5 of 53

 IBM Software Group

Choosing Type of Certificate

Step 2: Choosing Type of Certificate to Create

 Self-Signed
 CA – Signed by Certificate Authority

WebSphere ® Support Technical Exchange 6 of 53

 IBM Software Group

Creating Self-Signed Certificate

Click on Drop Down Arrow

beside Signer Certificates

Select Personal
Certificates

Click on New Self-Signed

WebSphere ® Support Technical Exchange 7 of 53

 IBM Software Group

Creating Self-Signed Certificates (cont)

Fill in Required Values

Press Ok

Certificate is now created

in the KeyStore

WebSphere ® Support Technical Exchange 8 of 53

 IBM Software Group

Creating a Certificate Request

Click on Drop Down Arrow

beside Signer Certificates

Select Personal Certificate

Requests

Click on New

WebSphere ® Support Technical Exchange 9 of 53

 IBM Software Group

Creating a Certificate Request (cont)

Fill in Required Values

Press Ok

Certificate Request is now

created in the file specified

You will now need to send

the file to a Certificate
Authority to request a
certificate.

WebSphere ® Support Technical Exchange 10 of 53

 ®

IBM Software Group

Exporting/Importing/Extracting Certificates
Using Ikeyman

WebSphere® Support Technical Exchange

 IBM Software Group

Exporting / Importing / Extracting Certificates

Exporting Private Key Pair

Extracting Public Certificate

Importing CA Certificate

WebSphere ® Support Technical Exchange 12 of 53

 IBM Software Group

Exporting Self-Signed Keypair From Keystore

Click on Drop Down Arrow

beside Signer Certificates

Select Personal
Certificates

Highlight Certificate

Click on Export/Import

WebSphere ® Support Technical Exchange 13 of 53

 IBM Software Group

Exporting Self-Signed Keypair From Keystore

 Select Export Key

 Select PKCS12 as Key File

Type

 Enter in File Name and

location

 Press Ok

 Provide Password to Protect

the key

 Press Ok

WebSphere ® Support Technical Exchange 14 of 53

 IBM Software Group

Extracting Public Certificate From Keystore

Click on Drop Down Arrow

beside Signer Certificates

Select Personal
Certificates

Highlight Certificate

Click on Extract Certificate

WebSphere ® Support Technical Exchange 15 of 53

 IBM Software Group

Extracting Public Certificate From Keystore

(cont)
Select Binary Der as Data
Type

Choose File Name and

Location

Press Ok
Send Certificate to
Participant

WebSphere ® Support Technical Exchange 16 of 53

 IBM Software Group

Importing CA Certificate Into Keystore

Click on Drop Down Arrow

Select Signer Certificates

Click on Add

Select Binary Der for Data

Type

Select File Name and

location

Press OK

WebSphere ® Support Technical Exchange 17 of 53

 ®

IBM Software Group

Managing Certificates Prior To Version 6.1.1

WebSphere® Support Technical Exchange

 IBM Software Group

Understanding Certificate Types

 Encryption / Decryption

 Digital Signature / Verification

 Client / Server Authentication

WebSphere ® Support Technical Exchange 19 of 53

 IBM Software Group

ENCRYPTION & DECRYPTION

WebSphere ® Support Technical Exchange 20 of 53

 IBM Software Group

Digital Signature & Verification

 Presentation text

WebSphere ® Support Technical Exchange 21 of 53

 IBM Software Group

Client/Server Authentication

WebSphere ® Support Technical Exchange 22 of 53

 ®

IBM Software Group

Setting Up Encryption/Decryption

WebSphere® Support Technical Exchange

 IBM Software Group

Inbound
 Load company.p12 as
Hub Operator’s PKCS12
Encryption certificate.

 Enable “AS Encryption”

in
the Participant Connection

 Send certificate to the

Participant

WebSphere ® Support Technical Exchange 24 of 53

 IBM Software Group

Outbound
Load Participant certificate
in the Participant profile as
encryption certificate. If
signed by a CA, install the
CA certificate in the Hub
Operator profile, as root.

Enable “AS Encrypted” in

the Participant Connection

WebSphere ® Support Technical Exchange 25 of 53

 ®

IBM Software Group

Setting up Digital Signature & Verification

WebSphere® Support Technical Exchange

 IBM Software Group

Inbound
Load [Link]
in the Participant
profile as digital
signature certificate.
If
signed by a CA,
install the CA
certificate in the Hub
Operator profile, as
root.
Enable “AS Signed”
in the Participant
Connection

WebSphere ® Support Technical Exchange 27 of 53

 IBM Software Group

Outbound

Load company.p12
as Hub Operator’s
PKCS12 digital
signature certificate.

Enable “AS Signed”

in the Participant
Connection

Send public
certificate to the
Participant

WebSphere ® Support Technical Exchange 28 of 53

 ®

IBM Software Group

Setting up Server Authentication

WebSphere® Support Technical Exchange

 IBM Software Group

Inbound
Import company.p12 to
the [Link] keystore.
Note: Starting with 6.1 the
[Link] is renamed to
[Link]

Define an HTTPS Target

Make sure the secure port

(default 57443) has been
defined at installation time
and is active)

WebSphere ® Support Technical Exchange 30 of 53

 IBM Software Group

Outbound
Load Participant certificate
as Hub Operator’s root
certificate

Define a HTTPS Gateway

in the Participant’s profile

Select that HTTPS

Gateway for the Participant
Connection

WebSphere ® Support Technical Exchange 31 of 53

 ®

IBM Software Group

Setting up Client Authentication

WebSphere® Support Technical Exchange

 IBM Software Group

Inbound
 Load Participant certificate (CA
or self-signed) in [Link]
Note: Starting with 6.1 the [Link]
is renamed to [Link]
 Run bcgClientAuth script to
enable Client SSL
 Turn Client Authentication ON:
bcghub/was/bin/[Link] –f
bcghub/scripts/[Link] -
conntype NONE set
 Turn Client Authentication OFF:
bcghub/was/bin/[Link] –f
bcghub/scripts/[Link] -
conntype NONE clear

WebSphere ® Support Technical Exchange 33 of 53

 IBM Software Group

Outbound
Load company.p12 as Hub Operator
PKCS12 ‘SSL Client’ Certificate

Define a HTTPS Gateway in the

Participant’s profile

Select that HTTPS Gateway for the

Participant Connection

Send the Certificate to the

Participant

WebSphere ® Support Technical Exchange 34 of 53

 ®

IBM Software Group

Changes in Certificate Management in

6.1.1 and Later

WebSphere® Support Technical Exchange

 IBM Software Group

What’s New
 All new wizard to simplify loading and configuring
certificates.
 New Features
 Certificates can be associated to internal partner’s.
 Multiple certificates can be loaded for same usage, e.g. Digital
Signature.
 Certificate sets to group primary and secondary certificates.
 Ability to vary certificates based on
 – Partner Pair
 – Operation Mode
 – Package
 Global settings for Internal partner.
 Where-Used capability for Certificates and Certificate Sets.
 Validate function in console, to validate certificates.

WebSphere ® Support Technical Exchange 36 of 53

 IBM Software Group

Multiple Certificates
In prior versions , Internal partners could have one
set of active certificates.
 Now, we can load multiple certificates for internal
partner for different Certificate Usage (Sign / Encrypt / SSL
Client)
Operation Mode (Production / Test)
 It allows user to vary certificates based on
 Partner Pair
 Operation Mode
 Package

WebSphere ® Support Technical Exchange 37 of 53

 IBM Software Group

Certificate Sets
 Introduced in this release to group a primary & secondary
certificate.
 User’s associate sets for Sign / Encrypt / Decrypt as
opposed certificates in 6.x.
 Set can be marked default so that it is used for ALL possible
combinations of
 Receiving partner
 Operation mode
 Package.

 Sets are applicable for,

 Internal Partners – Digital Sign & SSL Client
 External Partners - Encryption

WebSphere ® Support Technical Exchange 38 of 53

 IBM Software Group

Validate & Where-Used Function

Validate
 Allows users to make sure the certificate is valid
by checking
 Certificate Expiry
 Certificate path validation.
Where-Used
 Allows users to lookup participant connections
where a certificate set is used.

WebSphere ® Support Technical Exchange 39 of 53

 ®

IBM Software Group

Load Certificate Wizard Overview

WebSphere® Support Technical Exchange

 IBM Software Group

Certificate Load Wizard

Step1 : Certificate Location
 You can choose to upload a Public Certificate
(Individual / multiple from Trust-store ) / Private Key
(Individual / from Key-store )
 Step 2: End Entity and CA certificates
 If you are loading from a Key / Trust store you can
choose the certificate /certificate's to be uploaded
 Step 3: Certificate Details
 Provide details on certificate usage , Operation mode ,
primary / secondary
 Step 4: Set
 Associate the certificate to an existing certificate set /
a new certificate set

WebSphere ® Support Technical Exchange 41 of 53

 IBM Software Group

Certificate Load Wizard Contd..

 Step 5: Default Settings
 If the set in step 4 was defined as default it applies to all
receiving partner for all protocols, in this you will associate the
set to different operation modes.
 Step 6: Default Settings
 Associate the set to a combination of
– From / Sending partner ( ALL for Hub-operation &
specific for other External/internal partners)
– To Partner ( Choices are ALL or Specific external
partner)
– From Package (Choices are ALL or Specific Package)
– To Package (Choices are ALL or Specific Package)
– Operation Mode
– Certificate Usage

WebSphere ® Support Technical Exchange 42 of 53

 IBM Software Group

Certificate Load Wizard Contd..

Step 7: Associate Partners/Operation/Packages
 User will be taken to this page only if the set
was not default
 In this page they can associate the set to
internal partners / external partners.
 Also you can also associate this set to different
operation modes and packages.

WebSphere ® Support Technical Exchange 43 of 53

 ®

IBM Software Group

Troubleshooting

WebSphere® Support Technical Exchange

 IBM Software Group

Setting Up Logging and Tracing

Change Debug Level for All Servers to Finest

For SSL Related Issues

 Enable SSL Trace in WAS Console
 Turn on SSL property in WPG Console

Restart WPG Servers

WebSphere ® Support Technical Exchange 45 of 53

 IBM Software Group

Avoiding Certificate Chaining Errors

Symptom:
WPG will attempt to build and validate the certificate path if the bcg.build_complete_certpath= true
property is set in the [Link] file. This property is set to true by default. If the path can not be
verified you will receive the following errors in the bcg_router.log file:

StackTrace:[Link]: PKIXCertPathBuilderImpl could not build a valid

CertPath.; internal cause is:
[Link]: The certificate issued by OU=Class 3 Public Primary
Certification Authority, O="VeriSign, Inc.", C=US is not trusted; internal cause is:
[Link]: Certificate chaining error
at [Link](Unknown Source)
at [Link](Unknown Source)
at [Link]([Link])
at [Link]([Link])
at [Link]([Link])
at [Link]([Link])...
Further down in the trace, you will see another error in the bcg_router..log file where WPG can not find a
valid certificate:

StackTrace:[Link]: Could not get Valid encryption Certificate

at [Link]([Link])
at [Link]([Link])...

Resolution:
[Link]

WebSphere ® Support Technical Exchange 46 of 53

 IBM Software Group

SSL connection failure due to invalid

Certificate Revocation List (CRL)
Symptom:
WPG fails the SSL handshake with the gateway server issuing the following
error message in the bcg_router.log:
- ERROR [SSLPoster] [Gw_2_0] - [Link]: Certpath is
not valid .
The above error is usually preceded by the following debug statements:
- DEBUG [CertPathUtil] [Gw_22_2] - Verifying the certification path ...
- DEBUG [CertPathUtil] [Gw_22_2] - CertPathValidatorException : The
revocation status of the certificate with subject (CN=[Link], OU=Terms of
use at [Link]/rpa (c)00, OU=aaa, O=bbb, L=ccc, ST=ddd, C=ee)
could not be determined.
Resolution:
[Link]
rs=2310&context=SSDKJ8&context=SSDKKW&q1=crl&uid=swg2125838
5&loc=en_US&cs=utf-8&lang=en

WebSphere ® Support Technical Exchange 47 of 53

 IBM Software Group

[Link]: Unsupported
keysize or algorithm parameters
Symptom:
[Link]: [Link]: [Link]:
Error in loading the keystore: Private key decryption error:
([Link]: Unsupported keysize or algorithm parameters)
Resolution:
This error is caused by the JCE libraries used by the virtual java’s
machine executing WAS. This JVM is the standard version and it had a
limited support of cryptographic algorithm. To correct this you just
have to substitute two jar files in the configuration of the JVM IBM
(local_policy.jar and US_export_policy.jar).
These files are in the index $JAVA_HOME/jre/lib/security (for example
/usr/lib/jvm/jre-ibm/lib/security or
/opt/IBM/WebSphere/AppServer/java/jre/lib/security).
You can download the non limited libraries from
[Link] (file
[Link])

WebSphere ® Support Technical Exchange 48 of 53

 IBM Software Group

Useful Links
 WPG Support Page:
[Link]
support/

 Index of WPG Technotes:

[Link]

 IBM® Support Assistant:

[Link]

 Assist On Site:
[Link]

 IBM Support Toolbar:

[Link]

WebSphere ® Support Technical Exchange 49 of 53

 IBM Software Group

Summary
W e discussed how to manage certificates using ikeyman.

W e discussed how to setup Digital Signature, Encryption,

SSL Certificates before 6.11

W e discussed changes in Certificate Management in 6.1.1

and later.

W e discussed the certificate load wizard.

W e discussed some troubleshooting tips.

W e discussed some useful links.

WebSphere ® Support Technical Exchange 50 of 53

 IBM Software Group

Additional WebSphere Product Resources

 Discover the latest trends in WebSphere Technology and implementation, participate in
technically-focused briefings, webcasts and podcasts at:
[Link]

 Learn about other upcoming webcasts, conferences and events:

[Link]
 Join the Global WebSphere User Group Community:
[Link]
 Access key product show-me demos and tutorials by visiting IBM Education Assistant:
[Link]

 View a webcast replay with step-by-step instructions for using the Service Request (SR)
tool for submitting problems electronically:
[Link]
 Sign up to receive weekly technical My Notifications emails:
[Link]

WebSphere ® Support Technical Exchange 51 of 53

 IBM Software Group

Join WebSphere Support Technical Exchange on Facebook!

 Stay up-to-date on upcoming

webcast sessions
 Suggest future topics
 Suggest program
improvements
 Network with other product
users
 And More…

Become a fan now!

[Link]

WebSphere ® Support Technical Exchange 52 of 53

 IBM Software Group

Questions and Answers

WebSphere ® Support Technical Exchange 53 of 53