®

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 Participant.der
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 receiver.jks keystore.
Note: Starting with 6.1 the
receiver.jks is renamed to
bcgSecurityTrust.jks

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 ReceiverTrust.jks
Note: Starting with 6.1 the receiver.jks
is renamed to bcgSecurityTrust.jks
 Run bcgClientAuth script to
enable Client SSL
 Turn Client Authentication ON:
bcghub/was/bin/wsadmin.sh –f
bcghub/scripts/bcgClientAuth.jacl -
conntype NONE set
 Turn Client Authentication OFF:
bcghub/was/bin/wsadmin.sh –f
bcghub/scripts/bcgClientAuth.jacl -
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 bcg.properties 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:java.security.cert.CertPathBuilderException: PKIXCertPathBuilderImpl could not build a valid

CertPath.; internal cause is:
java.security.cert.CertPathValidatorException: The certificate issued by OU=Class 3 Public Primary
Certification Authority, O="VeriSign, Inc.", C=US is not trusted; internal cause is:
java.security.cert.CertPathValidatorException: Certificate chaining error
at com.ibm.security.cert.PKIXCertPathBuilderImpl.engineBuild(Unknown Source)
at java.security.cert.CertPathBuilder.build(Unknown Source)
at com.ibm.bcg.util.CertPathUtil.buildCertPath(CertPathUtil.java:454)
at com.ibm.bcg.util.CertPathUtil.validateCertPathWithReset(CertPathUtil.java:189)
at com.ibm.bcg.util.PKCS7Util.checkCertificateValidity(PKCS7Util.java:1490)
at com.ibm.bcg.util.PKCS7Util.encryptBytesS(PKCS7Util.java:292)...
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:com.ibm.bcg.util.BcgException: Could not get Valid encryption Certificate

at com.ibm.bcg.util.PKCS7Util.encryptBytesS(PKCS7Util.java:301)
at com.ibm.bcg.ediint.doc.ASDocBase.encrypt(ASDocBase.java:855)...

Resolution:
http://www-01.ibm.com/support/docview.wss?rs=2311&uid=swg21266207

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] - com.ibm.bcg.util.BcgException: 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=xxx.yyy.zzz, OU=Terms of
use at www.verisign.com/rpa (c)00, OU=aaa, O=bbb, L=ccc, ST=ddd, C=ee)
could not be determined.
Resolution:
http://www-01.ibm.com/support/docview.wss?
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

java.lang.SecurityException: Unsupported
keysize or algorithm parameters
Symptom:
java.lang.Exception: java.lang.Exception: java.io.IOException:
Error in loading the keystore: Private key decryption error:
(java.lang.SecurityException: 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
http://www-128.ibm.com/developerworks/java/jdk/security/142/ (file
unrestrict142.zip)

WebSphere ® Support Technical Exchange 48 of 53

 IBM Software Group

Useful Links
 WPG Support Page:
http://www-01.ibm.com/software/integration/wspartnergateway/
support/

 Index of WPG Technotes:

http://www-01.ibm.com/support/docview.wss?uid=swg27016406

 IBM® Support Assistant:

http://www-01.ibm.com/software/support/isa/

 Assist On Site:
http://www-01.ibm.com/support/assistonsite/

 IBM Support Toolbar:

http://www-01.ibm.com/software/support/toolbar/

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:
http://www.ibm.com/developerworks/websphere/community/

 Learn about other upcoming webcasts, conferences and events:

http://www.ibm.com/software/websphere/events_1.html
 Join the Global WebSphere User Group Community:
http://www.websphere.org
 Access key product show-me demos and tutorials by visiting IBM Education Assistant:
http://www.ibm.com/software/info/education/assistant

 View a webcast replay with step-by-step instructions for using the Service Request (SR)
tool for submitting problems electronically:
http://www.ibm.com/software/websphere/support/d2w.html
 Sign up to receive weekly technical My Notifications emails:
http://www.ibm.com/software/support/einfo.html

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!

http://www.facebook.com/pages/WebSphere-Support-Technical-Exchange/121293581419

WebSphere ® Support Technical Exchange 52 of 53

 IBM Software Group

Questions and Answers

WebSphere ® Support Technical Exchange 53 of 53