VERIFIED SOLUTION i

How to enable Digital Signatures in EngageOne Digital Delivery (formerly eMessaging)

The digital signature feature is only applicable to outbound e-mail messages sent by e-Messaging. If you are sending important communications to your customers via e-mail then it is important for your customers to be sure that the messages they receive:

• Are from the sender they appear to be
• Contain original and authentic content that has not been tampered with on route

The above can be ensured by the use of digital signatures. Therefore your organization should consider digitally signing the e-mail messages it sends to its customers. Applying a digital signature to the “complete” body of outbound e-mail messages is a standard feature that can be configured in e-Messaging. Signing the “complete” body means that all content, including attachments, get signed by the e-Messaging Digital Signature feature.

Digital signatures are based on Public Key Infrastructure (a.k.a. PKI). That means private and public keys are required for digital signatures to work. These keys are associated with digital certificates (format x.509 v3) which can be purchased from a Certificate Authority. Well known certificate authorities include Verisign and Thawte (see www.verisign.com and www.thawte.com). The Certificate Authority makes your public key available to recipient’s e-mail clients to validate that messages they receive from you are authentic. Your private key is, as its name suggests, private and should not be shared. e-Messaging needs the private key to create a digital signature for the messages it sends. It is important that the From address used by Outbound Profiles to send digitally signed messages is the same as the From address associated with the digital certificate! Otherwise the recipients of the messages will be warned by their e-mail client that your messages might be from a different sender to the one in the From address!

There are two files required by e-Messaging in order for it to digitally sign outbound messages. These are the private key file and keys.properties. The private key file store is an encrypted format and has a .p12 filename extension. The password to access the private key is specified when you download a digital certificate or when you export a digital certificate from your browser in .p12 format. This password also needs to be specified in keys.properties so that e-Messaging can access the private key.

When a new Vendor is created in e-Messaging using the Vendor Creation page, a folder called <install_path>/core.war/WEB-INF/classes/<vendor_name /Default_Keys is created and contains two files called replace_with_real_private_key.p12 and keys.properties. You must replace replace_with_real_private_key.p12 with a real digital certificate / private key combination and update the settings in keys.properties before you can use the digital signature function. Detailed instructions are provided below.

Whenever an Outbound Profile is saved with the Digitally Sign Message Body setting enabled:

• The folders for that Outbound Profile will include an <outbound_profile_name>/key folder containing a copy of the (default) digital certificate and associated private key (.p12 file) from: <install_path>/core.war/WEB-INF/classes/<vendor_name>/Default_Keys
• A folder called <install_path>/core.war/WEB-INF/classes/<vendor_name>/<outbound_profile_name> is created containing a copy of the (default) keys.properties file from: <install_path>/core.war/WEB-INF/classes/<vendor_name>/Default_Keys

Hence, if the From address used by the Outbound Profile is the same as the From address associated with the default digital certificate /private key then the Outbound Profile can be used immediately. If the From address is different then you will need to update the default digital certificate / private key in <outbound_profile_name>/key with one associated with that Outbound Profile’s From address and update the keys.properties file in: <install_path>/core.wa /WEB-INF/classes/<vendor_name>/Default_Keys accordingly.

For installations using WebLogic 10.3, the keys.properties and .p12 files need to be copied to the DOMAIN_HOME folder which is usually located under \user_projects\domains\

For example:
<WL install>/user-projects/domains/<EM domain> For installations using JBoss 5.1.0, the keys.properties and .p12 files need to be copied to the Classes and Default_Keys folders of the core.war. The path of these folders is given in the profile.xml file of JBoss 5.1.0.

For example, if C:\test is the path where core.war was copied, then the keys.properties and .p12 files need to be copied to C:\test\core.war\WEB-INF\classes & C:\test\core.war\WEB-INF\classes\<vendor_name>\Default_Keys.

Generating a Private Key

A private key is associated with a digital certificate. Some certificate authorities like www.thawte.com offer digital certificates free of charge if they are for personal use. You can order such a free digital certificate for test purposes by visiting the “Free Personal Email Certificate” section of the Thawte web site.

If your certificate authority provides you your digital certificate and associated private key as a .p12 file together with an associated password then this can be used directly in e-Messaging. Otherwise import the digital certificate into your browser. Some certificate authorities automatically install the digital certificate and associated private key on your web browser as part of their download process. If this happens then you will need to export the digital certificate and associated private key for use with e-Messaging. This can be done as follows:

• For Internet Explorer:
• Go to Tools -> Internet Options
• Select the Content tab
• Click on the Certificates button found in the Certificates section
• Locate the certificate you wish to export and click on the Export button
• Specify a directory/filename and password for the private key
• For Mozilla Firefox:
• Go to Tools -> Options
• Select Advance tab
• Select Encryption tab
• Click on the View Certificates button
• On the Your Certificate tab, select the certificate and click on the BackUp button
• Specify a directory/filename and password for the private key

NOTE THAT SOME CERTIFICATE AUTHORITIES REQUIRE YOU USE THE SAME WEB BROWSER ON THE SAME PC TO:
* PURCHASE A DIGITAL CERTIFICATE.
* DOWNLOAD THE CERTIFICATE ONCE IT HAS BEEN GRANTED.
* GENERATE A PRIVATE KEY FROM THE DIGITAL CERTIFICATE.

keys.properties

This property file contains settings to access your digital certificate’s private key so that e-Messaging can digitally sign outbound messages. The default keys.properties file for a given Vendor is located in:

<install_path>/core.war/WEB-INF/classes/<vendor_name>/Default_Keys

The keys.properties file actually used by a given Outbound Profile is located in:

<install_path>/core.war/WEB-INF/classes/<vendor_name>/<outbound_profile_name> keys.properties contains the following settings:

If you do not know the alias of the private key you wish to use, then this can be found by viewing the details of your digital certificate in your web browser.

• For Internet Explorer:
• Go to Tools -> Internet Options
• Select the Content tab
• Click on the Certificates button in the Certificates section
• Select the certificate you wish to view the alias name for and click on the View button
• Click the Details tab
• The alias is the value of the Friendly Name field
• For Mozilla Firefox:
• Go to Tools -> Options
• Select Advance tab

Property Description
keystore.password
the password to access the private key keystore.
key.alias
the alias of the private key in the keystore that is to be used
keystore.filename
the base filename of the keystore file located in outprofiles/<outbound_profile_name>/key. Note that generally this file has a .p12 file extension

AS DESCRIBED ABOVE THE DEFAULT KEYS.PROPERTIES IS COPIED TO <INSTALL_PATH>/CORE.WAR/WEB_INF/CLASSES/ <VENDOR_NAME>/<OUTBOUND_PROFILE_NAME> THE FIRST TIME AN OUTBOUND PROFILE IS SAVED.

WITH THE DIGITALLY SIGN MESSAGE BODY SETTING ENABLED. UPDATE THIS SETTING IN KEYS.PROPERTIES IF YOU DO NOT WISH TO USE THE DEFAULT PRIVATE KEY. FOR EXAMPLE IF THE DEFAULT PRIVATE KEY HAS A DIFFERENT E-MAIL ADDRESS ASSOCIATED THAN THE FROM ADDRESS USED BY AN OUTBOUND PROFILE, THEN THE DEFAULT PRIVATE KEY SHOULD BE REPLACED.

• Click on the View Certificates button
• Select the certificate you wish to view the alias name for and click on the View button
• Click the Details tab
• The alias is the value at the top of the tree in the Certificate Fields section

Triggering or Suppressing Digital Signing
There are two ways to enable the digital signature feature for e-mail messages sent by e-Messaging:
• In the Outbound Profile settings page, select the option Digitally Sign Message Body. This will cause all messages sent by an Outbound Profile to be digitally signed by default.
• Alternatively include a custom field in the DIJ (XML journal) with the name Sign and any of the following values: 1, true or yes. When Digitally Sign Message Body is enabled for an Outbound profile, it is still possible to disable the digital signature function on a message by message basis by:

• Including a custom field in the DIJ (XML journal) with the name Sign and any of the following values: 0, false or no.

Important Note
Due to import control restrictions, the version of Java (TM) Cryptography Extension (JCE) Policy files that are bundled in the JDK(TM) 6.0 environment allow "strong" but limited cryptography to be used. Your digital certificate might have been configured to use stronger encryption than the encryption supported by the default JCE policy files. This can result in error messages being written to the log files that start with:

Cannot unwrap key …
This means that the digital signing process is failing and therefore the messages are also
failing to be sent.

The solution is to upgrade your default JCE policy files with the "unlimited strength" policy files which contain no restrictions on cryptographic strengths.
For Sun's JDK, these can be downloaded from the following URL:

http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html

Replace your default JRE policy located in Program Files/java/jdk1.6.0_10/jre/lib/security with the local_policy.jar and US_export_policy.jar that you just downloaded. You will need to restart your application server for the new JCE policy files to take effect.

Note that the newly downloaded files do NOT contain any encryption functionality since such functionality is supported in Sun's JDK 6.0. Therefore, this installation applies only to Sun's JDK 6.0, and assumes that the JDK 6.0 is already installed.

For IBM's JDK (WebSphere), these can be downloaded from the following URL:

http://www.ibm.com/developerworks/java/jdk/security/50/#sdkpol
https://www14.software.ibm.com/webapp/iwm/web/preLogin.do?source=jcesdk

IBM's SDKs ship with strong but limited jurisdiction policy files. Unlimited jurisdiction policy files can be obtained from the link above. The ZIP file should be unpacked and the two JAR files placed in the JRE's jre/lib/security/ directory. These policy files are for use with IBM developed SDKs. The same files are used for the Version 1.4 and Version 5 SDKs. Details of downloads of unlimited jurisdiction policy files for the Solaris platform can be found in the IBM Security Guide for those platforms.

Replace your JRE policy located in: Program Files\IBM\WebSphere\AppServer\java\jre\lib\security with the local_policy.jar and US_export_policy.jar that you just downloaded. You will need to restart your application server for the new JCE policy files to take effect.
UPDATED:  March 23, 2017