5 Mail Service Administration

This chapter describes how to administer the mail service in Oracle Communications Convergence.

See "Enabling Core Services for Convergence" for information about enabling services.

About S/MIME

Support for Secure/Multipurpose Internet Mail Extension (S/MIME) 3.1 is available in Convergence. Convergence users who are set up to use S/MIME can exchange signed or encrypted messages with other Convergence users, Microsoft Outlook Express, and Mozilla mail systems.

The Convergence online help instructs end users in how to configure and send encrypted mail.

S/MIME provides a consistent way for email users to send and receive secure MIME data, using digital signatures for authentication, message integrity and non-repudiation and encryption for privacy and data security. S/MIME version 3.1 (RFC 3851) is supported.

You can deploy a secure mail solution using Oracle Communications Messaging Server that is configured with S/MIME. Convergence users who are set up to use S/MIME can exchange signed or encrypted messages with other users of Convergence, Microsoft Outlook Express, and Mozilla mail systems. A messaging proxy can provide an additional layer of security at the firewall to further protect information assets within Messaging Server.

The Convergence client supports S/MIME with these features:

• Create a digital signature for an outgoing mail message to assure the message's recipient that the message was not tampered with and is from the person who sent it

• Encrypt an outgoing mail message to prevent anyone from viewing, changing or otherwise using the message's content before the message arrives in the recipient's mailbox

• Verify the digital signature of an incoming signed message with a process involving a certificate revocation list (CRL)

• Automatically decrypt an incoming encrypted message so the recipient can read the message's contents

• Exchange signed or encrypted messages with other users of an S/MIME compliant client such as Convergence, Communications Express Mail, and Mozilla mail systems

To properly administer S/MIME, you need to be familiar with the following concepts:

• Digitally signed email messages

• Encrypted email messages

• Local key store of a browser

• Smart cards and the software and hardware to use them

• Private-public key pairs and their certificates

• Certificate authorities (CA)

• Verifying keys and their certificates

• Certificate revocation list (CRL)

Configuring Convergence with S/MIME

To support S/MIME, you must configure and store certificate information in Messaging Server and Directory Server.

In a typical deployment, these products run on server machines separate from the clients on which Convergence is running.

Table 5-1 lists the requirements for supporting S/MIME in Convergence.

Table 5-1 Requirements for S/MIME in Convergence on Client Machines

Component	Description
Private-public keys with certificates	One or more private-public key pair with certificates. Certificates are required and they must be in standard X.509 v3 format. Obtain keys and certificates from a CA for each Convergence user who will use the S/MIME features. The keys and their certificates are stored on the client machine or on a smart card. The public keys and certificates are also stored in an LDAP directory that can be accessed by Messaging Server and Convergence. A certificate revocation list (CRL), maintained by the CA, must be part of your system if you want key certificates checked against it to further ensure that the keys are valid. See "Accessing a CRL" for more information.
Smart card software (only required when keys and certificates are stored on smart cards)	ActivIdentity ActiveClient, Version 6.2, or Litronic NetSign 215 Reader CAC Compliant
Smart card reader	Any model of smart card reading device complying with ISO 7816 supported by the client machine and smart card software.

Certificate Requirements for Using S/MIME in Convergence

The signature and encryption features are not immediately available to Convergence users after you install Messaging Server. Before a user can take advantage of S/MIME, the requirements described in this information must be met.

Private and Public Keys

At least one private and public key pair, including a certificate in standard X.509 v3 format, must be issued to each Convergence user who will use S/MIME. The certificate, used in a verification process, assures other mail users that the keys really belong to the person who uses them. A user can have more than one key pair and associated certificate.

Keys and their certificates are issued from within your organization or purchased from a third-party vendor. Regardless of how the keys and certificates are issued, the issuing organization is referred to as a certificate authority (CA).

Key pairs and their certificates are stored in two ways:

• On a smart card

  These cards are similar to commercial credit cards and should be used and safeguarded by the mail user as they do their own credit cards. Smart cards require special card readers attached to the mail user's computer (client machine) to read the private key information. See "Keys Stored on Smart Cards" for more information.

• In a local key store on the mail user's computer (client machine)

  A mail user's browser provides the key store. The browser also provides commands to download a key pair and certificate to the key store. See "Keys Stored on the Client Machine" for more information.

Keys Stored on Smart Cards

If the private-public key pair, with its certificate, is stored on a smart card, a card reader must be properly attached to the mail user's computer. The card reading device also requires software; the device and its software are supplied by the vendor from whom you purchase this equipment.

There are actually two parts to a system with card reading capabilities. One part is the hardware card reader and it's driver. The second part is the actual card, which is usually provided by a different vendor and requires drivers for reading the cards. Not all cards are supported. Refer to "Configuring Convergence with S/MIME" to see a list of the supported smart cards (ActiveCard, now renamed ActiveIdentity, and NetSign).

When properly installed, a mail user inserts their smart card into the reading device when they want to create a digital signature for an outgoing message. After verification of their smart card password, the private key is accessible by Convergence to sign the message. See "Configuring Convergence with S/MIME" for information on supported smart cards and reading devices.

Libraries from the vendor of the smart card are required on the user's computer. See "Key Access Libraries for the Client Machines" for more information.

Keys Stored on the Client Machine

If key pairs and certificates are not stored on smart cards, they must be kept in a local key store on the mail user's computer (client machine). Their browser provides the key store and also has commands to download a key pair and certificate to the key store. The key store may be password-protected; this depends on the browser.

Libraries from the vendor of the browser are required on the user's computer to support a local key store. See "Key Access Libraries for the Client Machines" for more information.

Publish Public Keys in LDAP Directory

All public keys and certificates must also be stored to an LDAP directory, accessible by Messaging Server and Convergence. This is referred to as publishing the public keys so they are available to other mail users who are creating S/MIME messages. Public keys of the sender and receiver are used in the encrypting-decrypting process of an encrypted message.

Public key certificates are used to validate private keys that were used for digital signatures.

See "Managing Certificates for S/MIME" for more information on using ldapmodify to publish the public keys and certificates.

Give Mail Users Permission to Use S/MIME

To create a signed or encrypted message, a valid Convergence user must have permission to do so. This involves using the mailAllowedServiceAccess or mailDomainAllowedServiceAccess LDAP attributes for a user's LDAP entry. These attributes can be used to include or exclude mail users from S/MIME on an individual or domain basis.

See "Granting Permission to Use S/MIME Features" for more information.

Multi-language Support

A Convergence user who only uses English for their mail messages might not be able to read an S/MIME message which contains non-Latin language characters, such as Chinese. One reason for this situation is that the Java 6 Runtime Environment (JRE) installed on the user's machine does not have the charsets.jar file in the /lib directory.

The charsets.jar file is not installed if the English version of JRE was downloaded using the default JRE installation process. However, charsets.jar is installed for all other language choices of a default installation.

To ensure that the charsets.jar file is installed in the /lib directory, alert your users to use the custom installation to install the English version of JRE. During the installation process, the user must select the "Support for Additional Languages" option.

Wildcard SSL Certificates: Not Supported

While Wildcard SSL certificates enable SSL encryption on multiple subdomains with a single certificate, there are a number of security, certificate management, compatibility, and protection issues. Therefore, Wildcard SSL certificates are NOT supported in Convergence.

Configuring and Sending Encrypted Mail: Instructions for Convergence End Users

This section contains information to be made available to Convergence users for the sending of encrypted email messages.

Logging In for the First Time

When mail users log in to Convergence for the first time, they encounter special prompts relating to the S/MIME applet. For example:

• If the Java Runtime Environment (JRE) is not installed, users receive a popup asking them to install it. If users want to use S/MIME, they should accept and follow the subsequent prompts.

  Also, if users desire English language support and also want to read incoming S/MIME messages that contain non-Latin characters, such as Chinese, the charsets.jar file must be in the /lib directory on their computer.

  To ensure that the charsets.jar file is installed in the /lib directory, use the custom installation to install the English version of JRE. During the installation process, select the "Support for Additional Languages" option.

  See "Multi-language Support" for more information.

• If the signed applet certificates have not been accepted, users receive one or more prompts to accept signed and verified certificates. If users want to use S/MIME, they should accept the certificates.

Signature and Encryption Settings

There are initial signature and encryption settings that you can set to control whether all users' outgoing messages are:

• Automatically signed, or

• Automatically encrypted, or

• Automatically signed and encrypted

The initial settings also control whether the signature and encryption check boxes located at the top of a Convergence window and in the Options - Security window are displayed as checked (feature turned on) or unchecked (feature turned off). Use the alwaysencrypt and alwayssign parameters in the smime.conf file to specify the initial settings.

Let your mail users know that they can change the initial settings for their mail messages. After they log in to Convergence, a user can temporarily override a setting for one message, or for all their messages on an on-going basis.

Table 5-2 summarizes the use of the check boxes.

Table 5-2 Signature and Encryption Check Boxes in Convergence

Text for Check Box	Location	What Convergence User Does
Sign Message	At the top of the Convergence Compose tab (used for composing, forwarding, or replying to a message).	Check the box to sign the current message. Uncheck the box not to sign the current message.
Encrypt Message	At the top of the Convergence Compose tab (used for composing, forwarding, or replying to a message).	Check the box to encrypt the current message. Uncheck the box not to encrypt the current message.
Sign all outgoing Messages	In Convergence Options - Security dialog, under the Default Sending Settings heading:	Check the box to sign all your messages automatically. Uncheck the box not to sign all your messages automatically. Note: You can override the setting of "Sign all messages during send" on a message-by-message basis with the "Sign Message" check box.
Encrypt all outgoing Messages	In the Convergence Options - Security dialog, under the Default Sending Settings heading:	Check the box to encrypt all your messages automatically Uncheck the box not to encrypt all your messages automatically. Note: You can override the setting of "Encrypt all messages during send" on a message-by-message basis with the "Encrypt Message" check box.

Enabling the Java Console

A variety of operating messages can be written to the Java Console by the S/MIME applet as a Convergence user processes signed and encrypted messages. The Java Console messages can be helpful when troubleshooting a problem reported by a mail user. However, operating messages are only generated when the Java Console is enabled for the user by adding a nswmExtendedUserPrefs attribute to the inetMailUser object class of their LDAP entry. For example:

nswmExtendedUserPrefs: mesmimedebug=on

Do not enable the Java Console for all mail users all the time because this significantly decreases the performance of Convergence.

Securing Internet Links With SSL

The Messaging Server supports the use of the Secure Sockets Layer (SSL) for Internet links affecting Convergence.

For the link between Messaging Server and Convergence: securing this link with SSL requires administrative work for the Messaging Server. The Convergence user must use the HTTPS protocol, rather than HTTP, when entering the URL information for the Messaging Server in their browser. See "Securing the Link Between Messaging Server and Convergence" for more information.

For the link between Messaging Server and the S/MIME applet: When checking public keys certificates against a CRL, the S/MIME applet must communicate directly with the Messaging Server. Securing this link with SSL requires administrative work for the Messaging Server in addition to setting sslrootcacertsurl and checkoverssl in the smime.conf file. See "Securing the Link Between the Messaging Server and S/MIME Applet" for more information.

Securing the Link Between Messaging Server and Convergence

The Messaging Server supports the use of SSL for the Internet link between it and Convergence. Once you have set up Messaging Server for SSL, configure Convergence for SSL. See "About SSL in Convergence" for more information.

A Convergence user specifies the Convergence URL in their browser with the HTTPS protocol:

HTTPS://hostname.domain:SSL_port

instead of the HTTP protocol (HTTP://hostname.domain:port). When the Convergence login window displays, the user sees a lock icon in a locked position at the bottom of their window to indicate they have a secure link.

See Messaging Server System Administrator's Guide for information about configuring encryption and certificate-based authentication for SSL.

Securing the Link Between the Messaging Server and S/MIME Applet

When checking the certificate of a public key against a CRL, the S/MIME applet must communicate directly with the Messaging server.

To Secure the Communications Link with SSL

1. Configure the Messaging server for SSL. See the discussion about configuring encryption and certificate-based authentication in See Messaging Server System Administrator's Guide for information.

2. Set the sslrootcacertsurl parameter in the smime.conf file to specify the information to locate the root SSL CA certificates. These CA certificates are used to verify the Messaging Server's SSL certificates when the SSL link is established between the Messaging Server and the S/MIME applet.

3. Set the checkoverssl parameter in the smime.conf file to 1. This Messaging Server option determines whether SSL is used for the link between the Messaging Server and the S/MIME applet. Regardless of how a Convergence user specifies the URL for the Messenger Server (HTTP or HTTPS), the link between the Messaging Server and the S/MIME applet is secured with SSL when checkoverssl is set to 1.

Note:

A proxy server can be used between the Messaging Server and client applications such as Convergence. See "Proxy Server and CRL Checking" using a proxy server with and without a secured communications link.

Key Access Libraries for the Client Machines

Whether your mail users keep their private-public key pairs and certificates on a smart card or in a local key store of their browsers, key access libraries must be present on the client machines to support the storage methods.

The libraries are supplied by vendors of the smart cards and browsers. You must ensure that the correct libraries are on the client machines and specify the library name(s) with the appropriate platform parameter in the smime.conf file. The parameter is platformwin.

You can specify only the libraries you know are installed on the client machines or you can specify all the library names for a given platform and vendor if you are not sure what is installed. If the S/MIME applet does not find the library it needs among the names you specify, the S/MIME features do not work.

The syntax to specify one or more library filenames is:

platform_parameter==vendor:library=
library_name;...

where:

• platorm_parameter is the parameter name for the platform of the client machine where Convergence is accessed. Enter platformwin

• vendor specifies the vendor of the smart card or browser. Choose one of these literals:

  • CAC (for an ActivCard or NetSign smart card)

  • CAPI (for Internet Explorer with CAPI)

  • MOZILLA (for Mozilla with Network Security Services)

• library_name specifies the library filename.

The following libraries are required on the client machines when using Internet Explorer with Cryptographic Application Programming Interface (CAPI) on any Windows OS:

• acpkcs211.dll

• capibridge.dll

• softokn3.dll

• core32.dll

The following example specifies one smart card library and one Internet Explorer library, and one Mozilla library for a Windows platform:

platformwin==CAC:library=acpkcs211.dll;CAPI:library=capibridge.dll;
MOZILLA:library=softokn3.dll;

Verifying Private and Public Keys

Before Convergence Mail uses a private or public key, it must pass the verification tests shown in Figure 5-1. The remainder of this section describes the details of checking a public key's certificate against a CRL.

Figure 5-1 Private and Public Key Verification

Finding a User's Private or Public Key

When a Convergence Mail user has multiple private-public key pairs and multiple email addresses (primary, alternate, or alias addresses), it is possible that their keys are associated among their addresses. In this case, it is important that the S/MIME applet finds all the keys for verification purposes. Use the usercertfilter parameter in the smime.conf file to define a filter that creates a list of mail addresses for a key's owner at the time the public key's certificate is checked against a CRL. See the discussion about the smime.conf file and its parameters in the Messaging Server documentation for more information.

About Certificate Checking Against a CRL

A certificate revocation list, or CRL, is a list of revoked certificates maintained by the CA who issues the key pairs and certificates. When CRL checking is enabled, it causes the system to check the CRL whenever a certificate request has been made to see whether or not that certificate has been revoked.

When crlenable is set to 1 in the smime.conf file, a CRL test is performed after an unexpired key is found. The public key's certificate is checked against a CRL. There can only be one CRL for each CA, however the same CRL can be located in different places.

Checking a certificate against a CRL is done by the Messaging Server after the S/MIME applet sends it a request to do so. A public key certificate is used to validate a public key. Because a private key is kept secret, only used by the person who owns it, a private key cannot be checked directly against a CRL. To determine if a private key is good, the public key certificate of the key pair is used. When the public key's certificate passes the CRL test, the associated private key passes the test too.

Revocation of a certificate can happen for a variety of reasons, such as its owner has left your organization or lost the smart card. There are three situations for checking a certificate against a CRL:

• When an outgoing message is signed:

  The S/MIME applet always does this check unless you set sendsigncert to 0 or crlenable to 0.

• When an incoming signed message is read:

  The S/MIME applet always does this check unless you set readsigncert to 0 or crlenable to 0.

• When an outgoing message is encrypted:

  The S/MIME applet always does this check unless you set sendencryptcert to 0 or crlenable to 0.

Accessing a CRL

A certificate contains zero or more URLs, known as distribution points, that are used by Messaging Server to locate a CRL. If the certificate does not have a CRL URL, it cannot be checked against a CRL and the private or public key is used to sign or encrypt a message without knowing its true status.

If Messaging Server fails to locate or gain access to a CRL after trying all the URLs available to it, the status of the certificate is treated as unknown. Whether a private or public key with an unknown status is used is determined by the setting of revocationunknown.

While only one CRL for each CA is supported, there can be multiple copies of the same CRL in different locations, reflected in different URLs among a user's public key certificates. Messaging Server tries all the URL locations for a certificate until it gains access to the CRL.

You can manage multiple copies of a CRL for optimum access by periodically downloading the current CRL from the CA to a place where you want it. While you cannot change the URLs embedded in the certificates, you can redirect Messaging Server to use new CRL locations by mapping the URLs in a certificate to a new URL containing the CRL information. Create a list of one or more mapping definitions in the LDAP directory with this syntax:

msgCRLMappingRecord=url_in_certificate==
new_url[|url_login_DN|url_login_password]

url_in_certificate is the URL in the certificate containing the old information to locate the CRL. new_url is the new URL containing the new CRL information. url_login_DN and url_login_password are the DN and password of the entry allowed access to new_url. Both are optional, and if specified, will be used for the new URL access only.

If the DN and password fails, LDAP access is denied and no retry with other credentials is attempted. These login credentials are only valid for LDAP URLs. If you use crlurllogindn and crlurlloginpw in smmime.conf, then you don't need to specify the login DN and password in the mapping record. See "Accessing LDAP for Public Keys, CA certificates and CRLs Using Credentials".

Only one layer of mapping is allowed. Different URLs in the certificates can be mapped to the same new URL, but you cannot assign a certificate URL to multiple new URLs. For example, the following mapping list is not valid:

msgCRLMappingRecord=URL12==URL45
msgCRLMappingRecord=URL12==URL66
msgCRLMappingRecord=URL12==URL88
msgCRLMappingRecord=URL20==URL90
msgCRLMappingRecord=URL20==URL93

The next example is a correct mapping list:

msgCRLMappingRecord=URL12==URL45
msgCRLMappingRecord=URL14==URL66
msgCRLMappingRecord=URL88==URL66
msgCRLMappingRecord=URL201==URL90
msgCRLMappingRecord=URL202==URL93

Once you have created the mapping definitions in your LDAP directory, use crlmappingurl in the smime.conf file to specify the directory information to locate them. See the discussion about the smime.conf file and its parameters in the Messaging Server documentation for more information.

Proxy Server and CRL Checking

If your system uses a proxy server between client applications and the Messaging Server, CRL checking can be blocked despite the fact that you correctly configured the S/MIME applet to perform CRL checking. When this problem occurs, users of Convergence Mail receive error messages alerting them to revoked or unknown status for valid key certificates.

The following conditions cause the problem:

• CRL checking is requested with these configuration values:

  • crlenable parameter in the smime.conf file is set to 1

  • local.webmail.cert.enable option of Messaging Server is set to 1

• The communications link between the S/MIME applet and the proxy server is not secured with SSL, but the S/MIME applet is expecting a secured link because the checkoverssl parameter in the smime.conf file is set to 1

To solve this problem, you can:

• Set up the communications link between the client machines and proxy server as a secured link with SSL and leave all the configuration values as they are. Or,

• Leave the communications link unsecured and set checkoverssl to 0.

For more information see "Securing Internet Links With SSL".

Using a Stale CRL

Checking a certificate against a CRL is done by the Messaging Server after the S/MIME applet sends it a request to do so. Rather than download a CRL to memory each time a certificate is checked, Messaging Server downloads a copy of the CRL to disk and uses that copy for certificate checking. Every CRL has a next-update field which specifies the date after which a newer CRL version should be used. The next-update date can be viewed as an expiration date or time limit for using the CRL. A CRL that is past it's next-update date is considered old or stale and triggers Messaging Server to download the latest version of the CRL the next time a certificate is checked.

Every time the S/MIME applet requests that a certificate be checked against a CRL, the Messaging Server does the following:

1. Compares the current date to the next-update date of the CRL.

2. If the CRL is stale, the Messaging Server downloads the latest version of the CRL to replace the stale CRL on disk and checking proceeds. However, if a newer CRL cannot be found or cannot be downloaded, the value of crlusepastnextupdate in the smime.conf file is used to determine what to do.

3. If crlusepastnextupdate is set to 0, the stale CRL is not used and the certificate in question has an ambiguous status. The S/MIME applet uses the value of revocationunknown in smime.conf to determine what to do next:

   1. If revocationunknown is set to ok, the certificate is treated as valid and the private or public key is used to sign or encrypt a message.

   2. If revocationunknown is set to revoked, the certificate is treated as invalid, the private or public key is not used to sign or encrypt a message, and a pop-up error message alerts the mail user that the key cannot be used.

      If crlusepastnextupdate is set to 1, the S/MIME applet continues to use the stale CRL which causes no interruption of processing within Convergence Mail, however a message is written to the Messaging Server log file to alert you to the situation.

This sequence of events continues to occur as certificates are checked against the CRL. As long as the Messaging Server can download a newer version of the CRL in a timely manner, and depending on the settings in the smime.conf file, mail processing proceeds without interruption. Check the Messaging Server log periodically for repeated messages that indicate a stale CRL is in use. If a newer CRL cannot be downloaded, you need to investigate why it is inaccessible.

Determining Which Message Time to Use

The timestampdelta parameter is used primarily for these purposes:

1. To handle the situation of a message that takes a long time to arrive at its destination. For this case, the sender's key might be treated as an invalid key despite the fact that the key was valid when the message was sent.

2. To limit the trust in a message's sent time because sent times can be faked.

There are two times associated with every message:

• The time when the message was sent, as found in the Date line of the message header detail

• The time when the message arrives at its destination, as found in the last Received line of the message header detail

Note:

View the message header detail by clicking the triangle icon at the right hand side of a message's From field.

A certificate that was valid when a message was sent can be revoked or expired by the time the message reaches its destination. When this happens, which time should be used when checking the validity of the certificate, the sent time or the received time? Using the sent time would verify that the certificate was valid when the message was sent. But always using the sent time does not take into account the fact that it might take a long time for a message to arrive at its destination, in which case it would be better to use the received time.

You can influence which time to use for CRL checking by using the timestampdelta parameter in the smime.conf file. Set this parameter to a positive integer, representing seconds. If the received time minus the value of timestampdelta is a time before the sent time, the sent time is used. Otherwise, the received time is used. The smaller the value of timestampdelta, the more often the received time is used. When timestampdelta is not set, the received time is always used. In the Messaging Server documentation, see the discussion about the timestampdelta parameter in the smime.conf file.

Trouble Accessing a CRL

For a variety of reasons, such as network or server problems, a CRL might be unavailable when Messaging Server attempts to check a certificate against it. Rather than let the Messaging Server spend its time constantly trying to gain access to the CRL, you can use the crlaccessfail parameter in the smime.conf file to manage how often it attempts to access the CRL, freeing up the Messaging Server for other tasks.

Define the following with crlaccessfail:

• How many failed attempts are counted (an error message is written to the Messaging Server log after each failed attempt)

• Over what period of time the failed attempts are counted

• How long to wait before attempting a new cycle of accessing the CRL

In the Messaging Server documentation, see the discussion about the crlaccessfail parameter in the smime.conf file.

When a Certificate is Revoked

When a public key's certificate does not match any entry on the CRL, the private or public key is used to sign or encrypt an outgoing message. When a certificate matches an entry on the CRL or the certificate's status is unknown, a private or public key is considered revoked. By default Convergence Mail does not use a key with a revoked certificate to sign or encrypt an outgoing message. If the private key of a signed message is revoked by the time the recipient reads the message, the recipient receives a warning message indicating that the signature should not be trusted.

If desired, you can change the various default policies for all revoked certificates with the following parameters in the smime.conf file:

• Set sendsigncertrevoked to allow to sign an outgoing message with a private key that is considered revoked because its public key's certificate is revoked

• Set sendencryptcertrevoked to allow to encrypt an outgoing message with a public key that has a revoked certificate

• Set revocationunknown to ok to treat a certificate as valid whose status is unknown; the private or public key is used to sign or encrypt an outgoing message

Granting Permission to Use S/MIME Features

Permission to use the various mail services available through Convergence can be given or denied with LDAP filters. A filter is defined with the mailAllowedServiceAccess or mailDomainAllowedServiceAccess LDAP attributes. Generally speaking, a filter works in one of three ways:

• Permission to given to all users for all services when no filter is used

• Permission is explicitly given to a list of users for specified service names (a plus sign (+) precedes the service name list)

• Permission is explicitly denied to a list of users for specified service names (a minus sign (-) precedes the service name list)

The required mail service names for S/MIME are http, smime, and smtp. If you need to restrict the use of S/MIME among Convergence users, use the appropriate LDAP attribute syntax and service names to create a filter. The attributes are created or modified with LDAP commands.

S/MIME Permission Examples

The following examples block access to the S/MIME features for one Convergence user:

mailAllowedServiceAccess
mailAllowedServiceAccess: -smime:*$+imap,pop,http,smtp:*

or

mailAllowedServiceAccess: +imap,pop,http,smtp:*

The following examples block access to the S/MIME features for all Convergence users in a domain:

mailDomainAllowedServiceAccess: -smime:*$+imap:*$+pop:*$+smtp:*$+http:*

or

mailDomainAllowedServiceAccess: +imap:*$+pop:*$+smtp:*$+http:*

See the Messaging Server documentation for more information about filters and their syntax.

Managing Certificates for S/MIME

Most of the following examples use the ldapsearch and ldapmodify commands to search an LDAP directory for user keys and certificates. These commands are provided with Directory Server. See your Oracle Directory Server Enterprise Edition documentation for more information about the commands.

CA Certificates in an LDAP Directory

This example adds a certificate for a certificate authority to an LDAP directory. The directory structure for these certificates already exists. The certificate and the LDAP entries where it belongs are entered into the add-root-CA-cert.ldif file. All text is entered into the file in ASCII text except for the certificate information, which must be entered as Base64 encoded text:

dn: cn=SMIME Admin,ou=people,o=demo.siroe.com,o=demo
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: certificationAuthority
cn: RootCACerts
sn: CA
authorityRevocationList: novalue
certificateRevocationList: novalue
cacertificate;binary:: MFU01JTUUEjAQBgNVBAsTCU1zZ1NlcnZlcjcMBoGA1UEAxMTydG
QGEwJVUzEOMAwGA1UEMFUJTUUxEjAQBgNVBAsTCU1zZ1NlcnZlcjEMBoGA1UEAxMTQ2VydG
aFw0wNjAxMwODAwMDBaM267hgbX9FExCzAJByrjgNVBAk9STklBMQwCgYDVQQVHR8EgaQwg
YTAlVMRMQYDVQQIEwpDQUxJRk9STklBMQwwCgYDVQQKEwww3ltgYz11lzAdBgNVBpYSE9Vc
5yZWQaddWlm899XBsYW5ldC5jb20wgZ8wDQYJoGBAK1mUTy8vvnOFg4mlHjkghytQUR1k8l
5mvWRf77ntm5mGXRD3XMU4OciUq6zUfIg3ngvxlLyERTIqjUS8HQU4R5pvj+rrVgsAGjggE
+FNAJmtOV2A3wMyghqkVPNDP3Aqq2fkcn4va3C5nRNAYxNNVE84JJ0H3jyPDXhMBlQU6vQn
weMBAAjggEXMIIBEzARBglghkgBhCAQEEBApqlSai4mfuvjh02SQkoPMNDAgTwMB8GA1UdI
QYMBaAEd38IK05AHreiU9OYc6vNMOwZMIGsBgNVHR8EgaQwgaEwb6BtoGuGaWxkYXA6Lyht
bmcucmVkLmlbGFuZXQuY29tL1VJD1DXJ0aWZpY2F0ZSBNYW5hZ2VyLE9VPVBlb3BsZSxPPW
aWxxYT9jZXJ0aZpY2jdu2medXRllkghytQURYFNrkuoCygKoYoaHR0cDovL3Bla2kghytQU
Zy5yZWQuaXBsYW5lC5jb20vcGVranLmNybDAeBgNVHREEFzAVgRNwb3J0aWEuc2hhb0BzdW
4uY29tMA0GCxLm78freCxS3Pp078jyTaDci1AudBL8+RrRUQvxsMJfZeFED+Uuf10Ilt6kw
Tc6W5UekbirfEZGAVQIzlt6DQJfgpifGLvtQ60Kw==

The CA's certificate is added to the LDAP directory with an ldapmodify command:

ldapmodify -a -h demo.siroe.com -D "cn=Directory Manager" -w mypasswd -v
 -f add-root-CA-cert.ldif

The value of the trustedurl parameter in smime.conf specifies the location of the CA certificates in the LDAP directory. In the following example, trustedurl is set to:

trustedurl==ldap://demo.siroe.com:389/cn=SMIME Admin, ou=people, 
o=demo.siroe.com,o=demo?cacertificate;binary?sub?
(objectclass=certificationAuthority)

Public Keys and Certificates in an LDAP Directory

This example demonstrates adding a mail user's public key and certificate to the LDAP directory. It assumes the mail user already exists in the LDAP directory. The key and certificate, and the LDAP entries where it belongs, are entered into the add-public-cert.ldif file. All text is entered into the file as ASCII text except for the key and certificate information, which must be entered as Base64 encoded text.

dn: uid=JohnDoe,ou=People, o=demo.siroe.com,o=demo
changetype: modify
replace: usercertificate
usercertificate;binary:: MFU01JTUUxEjAQBgNVBAsT1zZ1NlcnZlcjMBoGA1UEAxMTydG
QGEwJVUzEAwGA1hMFU01JTUUxEjAQBgNVBAsTCU1zZ1NlcnZlcjEcMBoGA1UEAxMTQ2VydG
aFw0wNjAxMTODAwaM267hgbX9FExCzAJBgwyrjgNVBAk9STklBMQwwCgYDVQQVHR8EgaQwg
AlVzMRMwEQYDVQQIDQUxJRk9STklBMQwwCgYDVQQKEwww3ltgoOYz11lzAdBgNVBpYSE9Vc
5yZWaddiiWlm899XBsYW5ldb20wgZ8wDQYJoGBAK1mUTy8vvO2nOFg4mlHjkghytQUR1k8l
5mvgcWL77ntm5mGXRD3XMU4OcizUfIg3ngvxlLKLyERTIqjUS8HQU4R5pvj+rrVgsAGjggE
+FG9NAqtOV2A3wMyghqkVPNDP3Aqq2BYfkcn4va3RNAYxNNVE84JJ0H3jyPDXhMBlQU6vQn
1NAgMBGjggEXMIIBEzARBglghkgBhvhCAQEEBApqlSai4mfuvjh02SQMNDAgTwMB8GA1UdI
QYMBaEd38IK05AHreiU9OYc6v+ENMOwZMIGsBgNVHR8EgaQwgaEwb6BuGaWxkYXA6Lyht74
tpbmcmVkLmlwbGFuZXQuY29tL1VJRD1DZXJ0aWZpY2F0ZSBNYW5hZ2V9VPVBlb3BsZSxPPW
1haWxT9jZXJ0aWZpY2jdu2medXRllHjkghytQURYFNrkuoCygKoYoaHDovL3Bla2kghytQU
luZy5WQuaXBsYW5ldC5jb20vcGVraW5nLmNybDAeBgNVHREEFzAVgRNw0aWEuc2hhb0BzdW
4uY29A0GCxLm78UfreCxS3Pp078jyTaDv2ci1AudBL8+RrRUQvxsMJfZD+Uuf10Ilt6kwhm
Tc6W5UekbirfEZGAVQIzlt6DQJfgpifGLvtQ60Kw==

The ldapmodify command is used to add the public key and certificate to the LDAP directory:

ldapmodify -a -h demo.siroe.com -D "cn=Directory Manager" -w mypasswd -v
 -f add-public-cert.ldif

The value of the certurl parameter in smime.conf specifies the location of the public keys and their certificates in the LDAP directory. In the following example, certurl is set to:

certurl==ldap://demo.siroe.com:389/ou=people, o=demo.siroe.com, 
o=demo?userCertificate;binary?sub?

Verifying That Keys and Certificates Exist in the LDAP Directory

The following examples demonstrate searching an LDAP directory for CA certificates and public keys and their certificates.

Searching for One CA Certificate

In the following example, the base DN defined by the -b option, cn=SMIME admin, ou=people,o=demo.siroe.com,o=demo objectclass=*, describes one CA certificate in the LDAP directory. If found in the directory, ldapsearch returns information about the certificate to the ca-cert.lidf file.

ldapsearch -L -h demo.siroe.com -D "cn=Directory Manager" -w mypasswd -b
"cn=SMIME admin, ou=people,o=demo.siroe.com,o=demo" "objectclass=*" 
> ca-cert.ldif

The following example shows the search results in the ca-cert.ldif file. The format of the file's contents is a result of using the -L option of ldapsearch.

more ca-cert.ldif
dn: cn=SMIME admin,ou=people,o=demo.siroe.com,o=demo
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: certificationAuthority
cn: RootCACerts
cn: SMIME admin
sn: CA
authorityRevocationList: novalue
certificateRevocationList: novalue
cacertificate;binary:: MFU01JTUUxEjAQBgNVBAsTCU1zZNlcnZlcjcMBoGA1UEAxMTydG
QGEwJVEOMAwGA1UEChMFU0UUxEjAQBgNVBAsTCU1zZ1NlcnZlcjEcMBoGA1UEAxMTQ2VydG
aFw0jAxMTIwODAwMDBaM267X9FExCzAJBgwyrjgNVBAk9STklBMQwwCgYDVQQVHR8EgaQwg
YlVzMRMwEQYDVQQIEwpDQUx9STklBMQwwCgYDVQQKEwww3ltgoOYz11lzAdBgNVBpYSE9Vc
5yQuaddiiWlm899XBsYW5ljb20wgZ8wDQYJoGBAK1mUTy8vvO2nOFg4mlHjkghytQUR1k8l
5mcWRfL77ntm5mGXRD3XMciUq6zUfIg3ngvxlLKLyERTIqjUS8HQU4R5pvj+rrVgsAGjggE
+FNAJmqtOV2A3wMyghqkDP3Aqq2BYfkcn4va3C5nRNAYxNNVE84JJ0H3jyPDXhMBlQU6vQn
1NABAAGjggEXMIIBEzglghkgBhvhCAQEEBApqlSai4mfuvjh02SQkoPMNDAgTwMB8GA1UdI
QYMAFEd38IK05AHreOYc6v+ENMOwZMIGsBgNVHR8EgaQwgaEwb6BtoGuGaWxkYXA6Lyht74
tpbucmVkLmlwbGFuZY29tL1VJRD1DZXJ0aWZpY2F0ZSBNYW5hZ2VyLE9VPVBlb3BsZSxPPW
1haWYT9jZXJ0aWZpdu2medXRllHjkghytQURYFNrkuoCygKoYoaHR0cDovL3Bla2kghytQU
luZyZWQuaXBsYW5ldb20vcGVraW5nLmNybDAeBgNVHREEFzAVgRNwb3J0aWEuc2hhb0BzdW
4uYtMA0GCxLm78Ufre3Pp078jyTaDv2ci1AudBL8+RrRUQvxsMJfZeFED+Uuf10Ilt6kwhm
Tc6W5UekbirfEZGAVQIzlt6DQJfgpifGLvtQ60Kw==

Searching for a Several Public Keys

In the following example, the base DN defined by the -b option, o=demo.siroe.com,o=demo objectclass=*, is such that all public keys and certificates found at and below the base DN in the LDAP directory are returned to the file usergroup.ldif:

ldapsearch -L -h demo.siroe.com -D "cn=Directory Manager" -w mypasswd 
-b "o=demo.siroe.com,o=demo" "objectclass=*" > usergroup.ldif

Searching for One Public Key

In the following example, the base DN defined by the -b option, uid=JohnDoe, ou=people,o=demo.siroe.com,o=demo objectclass=*, describes one public key and its certificate in the LDAP directory:

ldapsearch -L -h demo.siroe.com -D "cn=Directory Manager" -w mypasswd -b 
"uid=JohnDoe, ou=people,o=demo.siroe.com,o=demo" "objectclass=*" > public-key.ldif

The following example shows the search results in the public-key.ldif file. The format of the file's contents is the result of using the -L option of ldapsearch.

more public-key.ldif
dn: uid=sdemo1, ou=people, o=demo.siroe.com, o=demo
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: siroe-am-managed-person
objectClass: inetOrgPerson
objectClass: inetUser
objectClass: ipUser
objectClass: userPresenceProfile
objectClass: inetMailUser
objectClass: inetLocalMailRecipient
objectClass: icsCalendarUser
objectClass: sunUCPreferences
mail: [e-mail]
mailHost: demo.siroe.com
.
.
uid: JohnDoe
.
.
mailUserStatus: active
inetUserStatus: active
.
.
usercertificate;binary:: MFU01JTUUxEjAQBgNBAsTCU1zZ1NlcnZjcMBoGA1UEAxMTydG
QGEwJEOwGA1UEChMFU01JTUUxEjAQBgNVBAsTCU1zZ1NlcnZlcjEcMBoGA1UEAxMTQ2VydG
aFw0MTIwODAwMDBaM267hgbX9FExCzAJBgwyrjgNVBAk9STklBMQwwCgYDVQQVHR8EgaQwg
YTAlVEQYDVQQIEwpDQUxJRk9STklBMQwwCgYDVQQKEwww3ltgoOYz11lzAdBgNVBpYSE9Vc
5yZWQdWlm899XBsYW5ldC5jb20wgZ8wDQYJoGBAK1mUTy8vvO2nOFg4mlHjkghytQUR1k8l
5mvgc7ntm5mGXRD3XMU4OciUq6zUfIg3ngvxlLKLyERTIqjUS8HQU4R5pvj+rrVgsAGjggE
+FG9NmV2A3wMyghqkVPNDP3Aqq2BYfkcn4va3C5nRNAYxNNVE84JJ0H3jyPDXhMBlQU6vQn
1NAgMAgEXMIIBEzARBglghkgBhvhCAQEEBApqlSai4mfuvjh02SQkoPMNDAgTwMB8GA1UdI
QYMBaEdK05AHreiU9OYc6v+ENMOwZMIGsBgNVHR8EgaQwgaEwb6BtoGuGaWxkYXA6Lyht74
tpbucmVkwbGFuZXQuY29tL1VJRD1DZXJ0aWZpY2F0ZSBNYW5hZ2VyLE9VPVBlb3BsZSxPPW
1haxYT9jZaWZpY2jdu2medXRllHjkghytQURYFNrkuoCygKoYoaHR0cDovL3Bla2kghytQU
luZyZWQuaYW5ldC5jb20vcGVraW5nLmNybDAeBgNVHREEFzAVgRNwb3J0aWEuc2hhb0BzdW
4u9tMA0GC78UfreCxS3Pp078jyTaDv2ci1AudBL8+RrRUQvxsMJfZeFED+Uuf10Ilt6kwhm
Tc6W5UekbirfEZGAVQIzlt6DQJfgpifGLvtQ60Kw==
.
.

Network Security Services Certificates

Various certificates used for Network Security Services (NSS) are stored in their own database, which is not an LDAP database. Two utilities, certutil and crlutil, are provided with Messaging Server to store the certificates and associated CRLs in the database. You can also use these utilities to search the database.

See the Directory Server documentation for more information about certutil. Use the help text that comes with crlutil for more information about that utility (view the online help of both utilities by executing them without arguments).

Configuring Messaging Server to Use S/MIME in Convergence

This section explains what the S/MIME applet is and provides a basic configuration procedure to set up S/MIME for Convergence. The configuration process involves setting parameters for the S/MIME applet and options for Messaging Server.

Overview of the S/MIME Applet

The process of signing a message, encrypting a message, or decrypting a message, along with the various procedures to verify private and public keys, are handled by a special applet, referred to as the S/MIME applet. The configuration of the S/MIME features is done with parameters in the smime.conf file and options of Messaging Server.

Figure 5-2 shows the S/MIME Applet in relation to other system components.

Figure 5-2 S/MIME Applet Location

The S/MIME applet is downloaded each time a user logs in to Convergence unless caching is enabled for the JRE on the user's machine. When caching is enabled, a copy of the S/MIME applet is saved on the user's machine after the initial download which prevents downloading the applet every time the user logs in.

Caching can improve performance so you might direct your users to enable caching, by following the instructions with the JRE.

Configuring S/MIME

The configuration file for S/MIME, smime.conf, contains descriptive comments and an example of each S/MIME parameter. The smime.conf file is included with Messaging Server, located in the directory Messaging_Server_Home/config/, where Messaging_Server_Home is the directory where Messaging Server is installed.

To configure S/MIME:

1. Verify that the basic features of Convergence are working after you install Messaging Server.

2. If you haven't already, create or obtain private-public key pairs, with certificates in standard X.509 v3 format, for all your mail users who have permission to use the S/MIME features.

3. If smart cards are used for keys and certificates:

   1. Distribute the smart cards to your mail users.

   2. Ensure that the smart card reading devices and software are properly installed on each client machine where Convergence is accessed.

4. If local key stores of the browsers are used to store keys and certificates, instruct your mail users how to download their key pairs and certificate to the local key store.

5. Ensure that the correct libraries are on the client machines to support smart cards or local key stores. See "Key Access Libraries for the Client Machines" for more information.

6. Set up your LDAP directory to support S/MIME:

   1. Store all certificates for the CAs in the LDAP directory, accessible by Directory Server, under the distinguished name for certificate authorities. The LDAP attribute for these certificates is cacertificate;binary. Write down the directory information where you store them. You'll need this information for a later step.

      See trustedurl in Table 5-3 for an example of specifying LDAP directory information.

   2. Store the public keys and certificates in the LDAP directory accessible by Directory Server. The LDAP attribute for public keys and certificates is usercertificate;binary. Write down the directory information where you store them. You'll need this information for a later step.

      See certurl in Table 5-3 for an example of specifying LDAP directory information.

   3. Ensure that all users who send or receive S/MIME messages are given permission to use S/MIME with an LDAP filter in their user entries. A filter is defined with the mailAllowedServiceAccess or mailDomainAllowedServiceAccess LDAP attributes. By default, if you do not use mailAllowedServiceAccess or mailDomainAllowedServiceAccess, all services including S/MIME, are allowed. If you explicitly specify services with these attributes, then the services HTTP and SMTP, and S/MIME, must be specified to give mail users permission to use the S/MIME features. See "Granting Permission to Use S/MIME Features" for more information.

7. Edit the smime.conf file with any available text editor. See comments at the beginning of the file for parameter syntax. All text and example parameters in smime.conf are preceded with a comment character (#). You can add the parameters you need to smime.conf or copy a parameter example to another part of the file and change its value. If you copy and edit an example, be sure to remove the # character at the beginning of its line. Add these parameters to the file, each on its own line:

   1. trustedurl (see Table 5-3): set to the LDAP directory information to locate the certificates of the CAs.

   2. certurl (see Table 5-3): set to the LDAP directory information to locate the public keys and certificates.

   3. usersertfilter (see Table 5-3): set to the value of the example in the smime.conf file. The example value is almost always the filter you want. Copy the example and delete the # character at the beginning of the line. This parameter specifies a filter definition for the primary, alternate, and equivalent email addresses of a Convergence user to ensure that all of a user's private-public key pairs are found when the key pairs are assigned to different mail addresses.

   4. sslrootcacertsurl (see Table 5-3): if you are using SSL for the communications link between the S/MIME applet and Messaging Server, set sslrootcacertsurl with the LDAP directory information to locate the certificates of CAs that are used to verify the Messaging Server's SSL certificates. See "Securing Internet Links With SSL" for more information.

   5. checkoverssl (see Table 5-3): set to 0 if you are not using SSL for the communications link between the S/MIME applet and Messaging Server.

   6. crlenable (see Table 5-3): set to 0 to disable CRL checking for now because doing CRL checking might require adding other parameters to the smime.conf file.

   7. logindn and loginpw (see Table 5-3): if the LDAP directory that contains the public keys and CA certificates requires authentication to access it, set these parameters to the distinguished name and password of the LDAP entry that has read permission.

      The values of logindn and loginpw are used whenever the LDAP directory is accessed with the LDAP information specified by the crlmappingurl, sslrootcacertsurl, or trustedurl parameters. See the discussion about the smime.conf file. Do not set logindn and loginpw if authentication is not required to access the LDAP directory.

8. Set the Messaging Server options with the configutil command

   1. local.webmail.smime.enable - set to 1.

   2. local.webmail.cert.enable - set to 1 if you want to verify certificates against a CRL. See "Messaging Server configutil Options for S/MIME" for more information.

9. Enable S/MIME in the Convergence server using the iwcadmin command:

   iwcadmin -o smime.enable -v true
   

10. Restart GlassFish Server.

11. Convergence is now configured for the S/MIME features. Verify that the S/MIME features are working with the following steps:

    1. Restart the Messaging server.

    2. Check the Messaging server log file: Messaging_Server_Home/log/http, for diagnostic messages relating to S/MIME.

    3. If any problems were detected for S/MIME, the diagnostic messages help you determine how to correct the problem with the configuration parameters.

    4. Correct the necessary configuration parameters.

    5. Repeat Steps a. through d. until there are no more diagnostic messages for S/MIME in the Messaging Server's log file.

    6. Check that the S/MIME features are working with the following steps:

    7. Log in to Messaging server from a client machine. Answer the special prompts for the S/MIME applet with Yes or Always. See "Managing Certificates for S/MIME".

    8. Compose a short message, addressed to yourself.

    9. Encrypt your message by checking the Encrypt check box at the bottom of the Compose window if it is not already checked.

    10. Click Send to send the encrypted message to yourself. This should exercise most of the mechanisms for keys and certificates.

    11. If you find problems with the encrypted message, the most likely causes are the values you used for LDAP directory information in the smime.conf file and/or the way keys and certificates are stored in the LDAP directory. Check the Messaging Server log for more diagnostic messages. Table 5-3 lists many options you might want to use to further configure your S/MIME environment. See the discussion about smime.conf file in the Messaging Server documentation for more information.

        Table 5-3 Messaging Server S/MIME Parameters for Convergence

        Required Parameters for S/MIME	Parameters for Smart Cards and Local Key Stores	Parameters for CRL Checking	Parameters for Initial Settings and Secured Links
        certurl*	platformwin	checkoverssl	alwaysencrypt
        logindn	NA	crlaccessfail	alwayssign
        loginpw	NA	crldir	sslrootcacertsurl
        trustedurl*	NA	crlenable	NA
        usercertfilter*	NA	crlmappingurl	NA
        NA	NA	crlurllogindn	NA
        NA	NA	crlurlloginpw	NA
        NA	NA	crlusepastnextupdate	NA
        NA	NA	readsigncert	NA
        NA	NA	revocationunknown	NA
        NA	NA	sendencryptcert	NA
        NA	NA	sendencryptcertrevoked	NA
        NA	NA	readsigncert	NA
        NA	NA	sendsigncertrevoked	NA
        NA	NA	timestampdelta	NA

        
        

You must specify a value for the certurl, trustedurl, and usercertfilter parameters because they have no default value.

Accessing LDAP for Public Keys, CA certificates and CRLs Using Credentials

Public keys, CA certificates, and CRLs required for S/MIME may be stored in an LDAP directory. The keys, certificates, and CRLs may be accessible from a single URL or multiple URLs in LDAP. For example, CRLs may be stored in one URL and public keys and certificates may be stored in another. Messaging Server allows you to specify which URL contains the desired CRL or certificate information, as well as the DN and password of the entry that has access to these URLs. These DN/password credentials are optional; if none are specified, LDAP access first tries the HTTP server credentials, and if that fails, it tries accessing it as anonymous.

Two pairs of smime.conf credential parameters may be set to access the desired URLs: logindn and loginpw, and crlurllogindn and crlurlloginpw.

logindn and loginpw are the credentials used for all URLs in smime.conf. They specify the DN and password of the LDAP entry that has read permission for the public keys, their certificates, and the CA certificates as specified by the certurl and trustedurl parameters.

crlurllogindn and crlurlloginpw specifies the DN and password of the LDAP entry that has read permission for the resulting URL from the mapping table (see "Accessing a CRL" for more information). If these credentials are NOT accepted, LDAP access is denied and no retry with other credentials is attempted. Either both parameters must be specified, or both must be empty. These parameters do not apply to the URLs that come directly from the certificate.

Setting Passwords for Specific URLs

Messaging Server allows you to specifically define the DN/ password pairs for accessing the following smime.conf URLs: certUrl, trustedUrl, crlmappingUrl, sslrootcacertsUrl.

The syntax is as follows:

url_typeURL [CommSuite:URL_DN | URL_password]

Example:

trustedurl==ldap://mail.siroe.com:389/cn=Directory Manager, ou=people,
o=siroe.com,o=ugroot?cacertificate?sub?(objectclass=certificationauthority) |
cn=Directory manager | boomshakalaka

Summary of Using LDAP credentials

This section summarizes the use of LDAP credentials.

• All LDAP credentials are optional; if none are specified, LDAP access first tries the HTTP server credentials, and if that fails, tries anonymous.

Two pairs of smime.conf parameters are used as credentials for the two sets of URLs that may be specified:

• logindn and loginpw - all URLs in smime.conf

• crlurllogindn and crlurlloginpw - all URLs from mapping table

These are known as the default LDAP credential pair.

• Any URL specified in smime.conf or via mapping CRL URLs can have an optional local LDAP credential pair specified.

• Credentials are checked in order in which each is specified:

  1. Local LDAP credential pair - if specified, only one tried

  2. Default LDAP Credential Pair - if specified, and no Local LDAP credential pair, only one tried

  3. Server - if neither Local LDAP credential pair nor default LDAP credential pair specified, first tried

  4. anonymous - last tried only if server fails or none specified

• If a URL has a Local LDAP credential pair specified, it is used first; if the access fails, access is denied.

• If a URL has no Local LDAP credential pair specified, the corresponding default LDAP credential pair is used; if access fails, then access is denied.

Messaging Server configutil Options for S/MIME

You can use the Messaging Server configuration utility to configure S/MIME options on Messaging Server.

To set S/MIME options using the Messaging Server configutil:

1. Log in to Messaging Server as root.

2. Change to the Messaging_Server_Home/sbin directory.

   where Messaging_Server_Home is the directory where Messaging Server is installed.

3. Set the Messaging Server options from Table 5-4 using the configutil as desired for your system. Unless stated otherwise, an option is not required to be set.

   Table 5-4 Messaging Server configutil Options for S/MIME

   Parameter	Description
   local.webmail.cert.enable	Controls whether the process that handles CRL checking should do CRL checking.0 - The process does not check a certificate against a CRL. This is the default.1 - The process checks a certificate against a CRL. When set to 1, ensure that the crlenable parameter in the smime.conf file is set to 1.
   local.webmail.cert.port	Specifies a port number on the machine where the Messaging Server runs to use for CRL communication. This port is used locally for that machine only. The value must be greater than 1024. The default is 55443. This is a required option if the default port number is already in use.
   local.webmail.smime.enable	Controls whether the S/MIME features are available to Convergence Mail users. Choose one of these values:0 - the S/MIME features are unavailable for Convergence Mail users even though the system is configured with the correct software and hardware components. This is the default.1 - the S/MIME features are available to Convergence Mail users who have permission to use them. Example: configutil -o local.webmail.smime.enable -v 1

   
   

Messaging Server smime.conf Parameters

The smime.conf file is included with the Messaging Server. The file is located in the directory Messaging_Server_Home/config/, where Messaging_Server_Home is the directory where Messaging Server is installed. All text and parameter examples in the file are preceded with a comment character (#).

You can add parameters with your values to the smime.conf file or you can edit the parameter examples. If using an example, copy the example to another part of the file, edit the parameter's value, and remove the # character at the beginning of the line.

Edit smime.conf with any available text editor after you install Messaging Server. The parameters, listed in Table 5-5, are not case sensitive and unless otherwise stated, are not required to be set.

Table 5-5 Messaging Server smime.conf Parameters

Parameter	Description
alwaysencrypt	Controls the initial setting for whether all outgoing messages are automatically encrypted for all Convergence users with permission to use S/MIME. Each Convergence user can override this parameter's value for their messages by using the check boxes described in "Signature and Encryption Settings". Choose one of these values:0 - do not encrypt messages. The encryption check boxes within Convergence are displayed as unchecked. This is the default.1 - always encrypt messages. The encryption check boxes within Convergence are displayed as checked. Example: alwaysencrypt==1
alwayssign	Controls the initial setting for whether all outgoing messages are automatically signed for all Convergence users with permission to use S/MIME. Each Convergence user can override this parameter's value for their messages by using the check boxes described in "Signature and Encryption Settings". Choose one of these values:0 - do not sign messages. The signature check boxes within Convergence are displayed as unchecked. This is the default.1 - always sign messages. The signature check boxes within Convergence are displayed as checked. Example: alwaysensign==1
certurl	Specifies the LDAP directory information to locate the public keys and certificates of Convergence users (the LDAP attribute for public keys is usercertificate;binary). See "Managing Certificates for S/MIME" for more information about certificates. This parameter must point to the highest node in the user/group of the LDAP directory information tree (DIT) that includes all users that are being served by the Messaging Server. This is particularly important for sites with more than one domain; the distinguished name must be the root distinguished name of the user/group tree instead of the subtree that contains users for a single domain. This is a required parameter that you must set. Example: certurl==ldap://mail.siroe.com:389/ou=people,o=siroe.com,o=ugroot
checkoverssl	Controls whether an SSL communications link is used when checking a key's certificate against a CRL. See "Securing Internet Links With SSL" for more information. Choose one of these values:0 - do not use an SSL communications link.1 - use an SSL communications link. This is the default. A problem can occur when a proxy server is used with CRL checking in effect. See "Proxy Server and CRL Checking".
crlaccessfail	Specifies how long to wait before the Messaging Server attempts to access a CRL after it has failed to do so after multiple attempts. This parameter has no default values. Syntax: crlaccessfail==number_of_failures:time_period_for_failures:wait_time_before_retry where:number_of_failures is the number of times that the Messaging Server can fail to access a CRL during the time interval specified by time_period_for_failures. The value must be greater than zero.time_period_for_failures is the number of seconds over which the Messaging Server counts the failed attempts to access a CRL. The value must be greater than zero.wait_time_before_retry is the number of seconds that the Messaging Server waits, once it detects the limit on failed attempts over the specified time interval, before trying to access the CRL again. The value must be greater than zero. Example: crlaccessfail==10:60:300 In this example, Messaging Server fails 10 times within a minute to access the CRL. It then waits 5 minutes before attempting to access the CRL again. See "Trouble Accessing a CRL".
crldir	Specifies the directory information where the Messaging Server downloads a CRL to disk. The default is Messaging_Server_Home/data/store/mboxlist, where Messaging_Server_Home is the directory where Messaging Server is installed. See "Using a Stale CRL" for more information.
crlenable	Controls whether a certificate is checked against a CRL. If there is a match, the certificate is considered revoked. The values of the send*revoked parameters in the smime.conf file determine whether a key with a revoked certificate is rejected or used by Convergence. See "Verifying Private and Public Keys" for more information. Choose one of these values:0- each certificate is not checked against a CRL.1- each certificate is checked against a CRL. This is the default. Ensure that thelocal.webmail.cert.enable option of the Messaging Server is set to 1, otherwise CRL checking is not done even if crlenable is set to 1.
crlmappingurl	Specifies the LDAP directory information to locate the CRL mapping definitions. This parameter is only required when you have mapping definitions. See "Accessing a CRL" optionally add the DN and password that has access to the URL. Syntax: crlmappingurlURL [|URL_DN |URL_password] Example: crlmappingurl==ldap://mail.siroe.com:389/ cn=XYZ Messaging, ou=people, o=mail.siroe.com,o=isp?msgCRLMappingRecord?sub? ( objectclass=msgCRLMappingTable) | cn=Directory Manager | pAsSwOrD
crlurllogindn	Specifies the distinguished name of the LDAP entry that has read permission for the CRL mapping definitions (not if the entry is directly from the certificate, see "Accessing a CRL"). If values for crllogindn and crlloginpw are not specified, the Messaging Server uses the log in values for the HTTP server to gain entry to the LDAP directory. If that fails, Messaging Server attempts to access the LDAP directory anonymously. Example: crllogindn==cn=Directory Manager
crlurlloginpw	Specifies the password, in ASCII text, for the distinguished name of thecrllogindn parameter. If values for crllogindn and crlloginpw are not specified, Messaging Server uses the log in values for the HTTP server to gain entry to the LDAP directory. If that fails, Messaging Server attempts to access the LDAP directory anonymously. The value may be obfuscated with base64 by using $== instead of == as the delimiter (this feature was introduced in Messaging Server 7 Update 1). Example: crlloginpw==zippy orcrlloginpw$==emlwcHk=
crlusepastnextupdate	Controls whether a CRL is used when the current date is past the date specified in the CRL's next-update field. See "Using a Stale CRL" for more information. Choose one of these values:0 - do not use the stale CRL.1 - use the stale CRL. This is the default.
logindn	Specifies the distinguished name of the LDAP entry that has read permission for the public keys and their certificates, and the CA certificates located in the LDAP directory specified by the certurl and trustedurl parameters. If values for logindn and loginpw are not specified, the Messaging Server uses the log in values for the HTTP server to gain entry to the LDAP directory. If that fails, Messaging Server attempts to access the LDAP directory anonymously. Example: logindn==cn=Directory Manager
loginpw	Specifies the password, in ASCII text, for the distinguished name of the logindn parameter. If values for logindn and loginpw are not specified, Messaging Server uses the log in values for the HTTP server to gain entry to the LDAP directory. If that fails, Messaging Server attempts to access the LDAP directory anonymously. The value may be obfuscated with base64 by using $== instead of == as the delimiter (this feature was introduced in Messaging Server 7 Update 1). Example: loginpw==SkyKing orloginpw$==U2t5S2luZw==
platformwin	Specifies one or more library names that are necessary when using smart cards or a local key store on a Windows platform. Change this parameter only if the default value does not work for your client machines. The default is:platformwin==CAPI:library=capibridge.dll; See "Key Access Libraries for the Client Machines" for more information.
readsigncert	Controls whether a public key's certificate is checked against a CRL to verify an S/MIME digital signature when the message is read. (A private key is used to create a digital signature for a message but it cannot be checked against a CRL, so the certificate of the public key associated with the private key is checked against the CRL.) See "Verifying Private and Public Keys". Choose one of these values:0 - do not check the certificate against a CRL.1 - check the certificate against a CRL. This is the default.
revocationunknown	Determines the action to take when an ambiguous status is returned when checking a certificate against a CRL. In this case, it is not certain whether the certificate is valid or has a revoked status. See "Verifying Private and Public Keys" for more information. Choose one of these values: ok - treat the certificate as valid.revoked - treat the certificate as revoked. This is the default.
sendencryptcert	Controls whether the certificate of a public key that is used to encrypt an outgoing message is checked against a CRL before using it. See "Verifying Private and Public Keys". Choose one of these values:0 - do not check the certificate against a CRL.1 - check the certificate against a CRL. This is the default.
sendencryptcertrevoked	Determines the action to take if the certificate of a public key that is used to encrypt an outgoing message is revoked. See "Verifying Private and Public Keys" for more information. Choose one of these values: allow - use the public key.disallow - do not use the public key. This is the default.
sendsigncert	Controls whether a public key's certificate is checked against a CRL to determine if a private key can be used to create a digital signature for an outgoing message. (A private key is used for a digital signature but it cannot be checked against a CRL, so the certificate of the public key associated with the private key is checked against the CRL.) See "Verifying Private and Public Keys" for more information. Choose one of these values:0 - do not check the certificate against a CRL.1 - check the certificate against a CRL. This is the default.
sendsigncertrevoked	Determines the action to take when it is determined that a private key has a revoked status. (A private key is used to create a digital signature for a message but it cannot be checked against a CRL, so the certificate of the public key associated with the private key is checked against the CRL. If the public key certificate is revoked, then its corresponding private key is also revoked.) See "Verifying Private and Public Keys" for more information. Choose one of these values: allow - use the private key with a revoked status.disallow - do not use the private key with a revoked status. This is the default.
sslrootcacertsurl	Specifies the distinguished name and the LDAP directory information to locate the certificates of valid CAs which are used to verify the Messaging Server's SSL certificates. This is a required parameter when SSL is enabled in the Messaging Server. See "Securing Internet Links With SSL" for more information. If you have SSL certificates for a proxy server that receives all requests from client application, the CA certificates for those SSL certificates must also be located in the LDAP directory pointed to by this parameter. You can also optionally add the DN and password that has access to the URL. Syntax: crlmappingurlURL [|URL_DN |URL_password] Example: sslrootcacertsurl==ldap://mail.siroe.com:389/cn=SSL Root CA Certs,ou=people,o=siroe.com,o=isp? cacertificate; binary?base? (objectclass=certificationauthority)|cn=Directory Manager | pAsSwOrD
timestampdelta	Specifies a time interval, in seconds, that is used to determine whether a message's sent time or received time is used when checking a public key's certificate against a CRL. The parameter's default value of zero directs Convergence to always use the received time. See "Determining Which Message Time to Use" for more information. Example: timestampdelta==360
trustedurl	Specifies the distinguished name and LDAP directory information to locate the certificates of valid CAs. This is a required parameter. You can also optionally add the DN and password that has access to the URL. Syntax: crlmappingurlURL [|URL_DN |URL_password] Example: trustedurl==ldap://mail.siroe.com:389/cn=Directory Manager, ou=people, o=siroe.com,o=ugroot?cacertificate?sub? (objectclass=certificationauthority)| cn=Directory Manager | pAsSwOrD
usercertfilter	Specifies a filter definition for the primary, alternate, and equivalent email addresses of a Convergence user to ensure that all of a user's private-public key pairs are found when they are assigned to different mail addresses. This parameter is required and has no default values.

Managing Attachment Previewing

By default, Convergence can preview only JPG, GIF, and TXT email attachments. In a desktop environment, native applications must be installed to view email attachments such as Office documents, or browser plug-ins must be installed in the browser to enable Convergence to preview PDF attachments.

If Convergence is integrated with Oracle Outside In Transformation Server, Convergence is capable of previewing many different file types regardless of the web browser, including DOC and XLS type email attachments.

See Convergence Installation and Configuration Guide for information about installing Outside In Transformation Server and configuring it for Convergence.

About Outside In Transformation Server and the Outside In Proxy

Each time a user previews an attachment, Convergence attempts to open it in the browser. If Convergence is not able to open the attachment by default, it sends the attachment to Outside In Transformation Server. The transformation server transforms the attachment into HTML, which Convergence can render in the browser.

The transformation server can handle a large number of simultaneous requests by placing attachment requests in a queue.

The Outside In proxy creates a temporary directory for each user requesting to view attachments. For each transformation, the Outside In proxy creates a temporary subdirectory under the user directory. The Outside In proxy passes the input directory containing the transformed attachment and the output directory of the transformed attachment to the Transformation Server. The Outside In proxy deletes the subdirectory after a configurable time-out period has passed.

The Convergence server manages file management to the transformation server. Convergence uses a session cookie and a server-generated URL token for each attachment request. For security, Convergence masks the URL token.

Figure 5-3 shows the attachment preview workflow.

Figure 5-3 Convergence Attachment Request Workflow

The following list explains the attachment preview workflow from Figure 5-3.

1. The Convergence client sends the request to the Convergence server.

   If the request is for an attachment type that can be rendered natively in the browser, the request is sent to the WMAP proxy.

   If the request is for an attachment type that cannot be rendered natively in the browser, the request is first passed to the Outside In proxy, and then to the WAMP proxy.

2. The request is sent to the Messaging server. The Messaging server sends the attachment back to the Convergence server.

3. For attachment types that cannot be rendered natively in the browser, the Outside In proxy sends the response from the Messaging server to the disk storage.

4. For attachment types that cannot be rendered natively in the browser, the Outside In proxy communicates where it saved the attachment to the Outside In Transformation server, and also informs the transformation server where to save the attachment after it has been converted.

5. For attachment types that cannot be rendered natively in the browser, the transformation server converts the attachment into a format that can be natively rendered in the browser and saves it to the directory provided by the Outside In proxy.

6. For attachment types that cannot be rendered natively in the browser, the transformation server informs the Outside In proxy that it has completed transforming the file.

7. If the original request was for an attachment type that could be rendered native in the browser, the Convergence server sends the attachment to the browser.

   If the original request was for an attachment type that could not be rendered native in the browser, the Outside In proxy provides the browser with a redirection URL to the transformed attachment on the disk storage.

8. If the original request was for an attachment type that could not be rendered native in the browser, the Convergence client accesses the transformed attachment using the URL provided by the Outside In proxy and renders it in the browser.

Configuring File Directory Access

Convergence and Outside In Transformation Server have to be configured so that they can both read and write attachments in the storage disk. Convergence must have full permissions to the storage disk to read, write, and delete files.

The Convergence Server and the Outside In Transformation Server can run on the same machine or on different machines. Configure the transformation server as a network file system (NFS).

• If the transformation server is running on Solaris:

  • Share the /export/tsdir/ directory.

    chmod 700 /export/tsdir
    

  • Edit /etc/dfs/dfstab and add the following line:

    share -F nfs -d [-o root=host_name] "tsdir" /export/tsdir
    

    Include the -o parameter when the Convergence server and the transformation server are running as local root, where host_name is the host name of the Convergence server. Omit the -o parameter when the Convergence server and the transformation server are running as the same user.

  • Create a soft link or mount to the NFS directory. For example:

    -s //net/host_name/export/tsdir /export/tsdir
    

• If the transformation server is running on Linux:

  • Share the /export/tsdir/ directory:

    chmod 700 /export/tsdir
    

  • If the Convergence server and the transformation server are running as the same user, edit /etc/exports and add the following line:

    /export/tsdir
    

    If the Convergence server and the transformation server are running as local root, edit /etc/exports and add the following line:

    /export/tsdir host_name(rw,no_root_squash)
    

  • Create a soft link or mount to the NFS directory. For example:

    -s //net/host_name/export/tsdir /export/tsdir
    

The Outside In proxy generates a unique URL for each attachment and provides it to the Convergence client.

The following example shows the sample configuration settings for Outside In proxy in the Convergence configuration.xml file:

<OINService>
     <ServiceName v="SUN_OIN_SERVICE"/>
     <BackendServiceDetails>
          <Enable v="true"/>
          <HostName v="oin server name"/>
          <PortNumber v="60611"/>
     </BackendServiceDetails>
     <TsdirPath v="/export/tsdir"/>
     <AutoPruneInterval v="5"/>
</OINService>

You can use the iwcadmin command to configure the parameters for the Outside In proxy.

Managing Attachment Life Cycles

The Outside In proxy manages the life cycle of attachments, including temporary directories, file creation, deletion, and purging, and the number of directories and disk space per user.

By default, the Outside In proxy automatically deletes an attachment from the storage disk after five minutes.

Use the iwcadmin command to configure the duration after which attachments are deleted from the storage disk. For example, to configure the proxy to delete attachments from the disk after three minutes:

iwcadmin -o oin.autopruneinterval -v 3

Supporting Extended Character Locales

Oracle Outside In Transformation Server supports many typical font sets and some extended font sets. However, depending on the locales being used in your deployment, you may need to install and configure additional font sets to support the rendering of attachments.

By default, when the transformation server cannot render characters because the font is missing, it replaces the character with an asterisk. For example, if a user is using Convergence with the Japanese locale, but the transformation server does not have access to Japanese font sets, the transformation server will render attachments with asterisks.

Install all required fonts on the host machine where the transformation is installed and export the GDFONTPATH environment variable.

See the Oracle Outside In Technology documentation for more information.

Customizing Transformation Blacklist

The Outside In Transformation Server blacklist enumerates the types of files that are prevented from being sent to the transformation server, such as ZIP files or EXE files.

You can customize the blacklist to add or remove file types. See the discussion about customizing the attachment blacklist in Convergence Customization Guide for more information.

About HTML Filtering

You can configure Convergence to filter embedded HTML content from email messages, because such content could contain malicious code. By default, HTML filtering is enabled. When HTML filtering is enabled:

• Convergence removes specified elements, attributes, protocols, and CSS properties from incoming email messages before routing the messages to users.

• Convergence provides an option to allow the URLs in inline styles in email messages. This can be set by using the mail.htmlsanitizer.allowurlsinstyle parameter. This option should be enabled only when the URL referenced in the email message is from trusted source and is secure. See "Convergence Properties Reference" for information on mail.htmlsanitizer.allowurlsinstyle.

Convergence includes a default whitelist, a blacklist, a CSS whitelist of HTML elements, attributes, protocols, and CSS properties. Whitelisted and CSS whitelisted entries are permitted in email messages. Blacklisted entries are removed from email messages. Elements, attributes, protocols, and CSS properties that do not appear on any of these whitelists are treated as blacklist entries.

Figure 5-4 shows the approach that is used for HTML filtering in Convergence.

Figure 5-4 HTML Filtering in Convergence

Configuring HTML filtering consists of the following tasks:

• Enabling and Disabling HTML Filtering

• Configuring HTML Filtering in Convergence

Enabling and Disabling HTML Filtering

You enable and disable HTML filtering using the iwcadmin command. By default, HTML filtering is enabled.

To enable or disable HTML filtering, enter:

iwcadmin -o mail.htmlsanitizer.enable -v {true|false}

when the mail.htmlsanitizer.enable parameter is set to false, HTML content is not displayed in the email message. Only the text or plain content is displayed in the Convergence email message. To display the HTML content, set the role.http.convergencefilterenabled parameter to true in the Messaging Server. See the discussion about HTML Filtering in your Messaging Server documentation.

Note:

In Convergence 3.0.1 patch sets, the HTML filtering is disabled by default. If you are installing Convergence 3.0.1 patch sets, see Table 5-6 for the information on recommended configurations for HTML filtering in Convergence and Messaging Server.

Table 5-6 Recommended Configurations for HTML Filtering in Different Releases of Convergence and Messaging Server

Convergence	Messaging Server	Recommended Configuration in Convergence	Recommended Configuration in Messaging Server
3.0.2 X	8.0.2.2 and later	mail.htmlsanitizer.enable = true	No additional configurations required
3.0.2 X	8.0.2.2 and later	mail.htmlsanitizer.enable = false	http.convergencefilterenabled = 1 http.enableblacklistfilter = 1
3.0.1.1.0 to 3.0.1.4.0	8.0.2 to 8.0.2.1	mail.htmlsanitizer.enable = true/false	http.convergencefilterenabled = 1 http.enableblacklistfilter = 1
3.0.1.1.0 to 3.0.1.4.0	Below 8.0.2	mail.htmlsanitizer.enable = true/false	No additional configurations available
Below 3.0.1.1.0	Below 8.0.2	No additional configurations available	No additional configurations available

Note:

Convergence releases before 3.0.1.1.0 release were completely dependent on the blacklist based filtering provided by Messaging Server for HTML filtering. Whitelist based filtering was introduced in Convergence 3.0.1.1.0 release. Oracle recommends Convergence for HTML filtering rather than Messaging Server.The blacklist filter (http.enableblacklistfilter) has been disabled from Messaging Server 8.0.2 release onwards and a new parameter, http.convergencefilterenabled, has been introduced for HTML filtering. Only when this parameter is set to 1, mshttpd will send HTML content in the message body and expects the content to be sanitized by Convergence.

Configuring HTML Filtering in Convergence

The default Convergence whitelist includes all known safe HTML elements, attributes, and protocols. The default Convergence blacklist includes all known potentially harmful HTML elements, attributes, and protocols. The default Convergence CSS whitelist includes all known safe CSS properties.

Blacklist takes precedence over whitelist; that is, if an element is present in both whitelist and blacklist, the element will be considered as blacklisted and the element will not be allowed in the email content.

You use the iwcadmin command to create an additional whitelist, blacklist, CSS whitelist with additional elements, attributes, protocols, or CSS properties.

It is not possible to modify the default whitelist, blacklist, or CSS whitelist. The contents of the default lists are deliberately excluded from this documentation, as such information could be used to target whitelisted values.

To configure the additional blacklist:

iwcadmin -o mail.htmlsanitizer.additionalblacklist -v "filtering_value"

To configure the additional whitelist:

iwcadmin -o mail.htmlsanitizer.additionalwhitelist -v "filtering_value"

To configure the additional CSS properties for whitelist:

iwcadmin -o mail.htmlsanitizer.additionalCSSwhitelist -v "filtering_value"

Where filtering_value is a comma-separated list of HTML elements, attributes, protocols, or CSS properties.

The following example shows a sample configuration using the additional blacklist:

• Do not allow attribute1 and attribute2 on all elements

• iwcadmin -o mail.htmlsanitizer.additionalblacklist -v "attribute1, attribute2"
  

• Do not allow attribute1 on element1 only.

  iwcadmin -o mail.htmlsanitizer.additionalblacklist -v "attribute1@element1"
  

• Do not allow element1 and element2.

  iwcadmin -o mail.htmlsanitizer.additionalblacklist -v "@element1,@element2"
  

• Do not allow element1. Do not allow attribute1 on any element. Do not allow attribute2 on element2.

  iwcadmin -o mail.htmlsanitizer.additionalblacklist -v "@element1,attribute1, attribute2@element2"
  

• Do not allow attribute1, attribute2 and attribute3 on element1.

  iwcadmin -o mail.htmlsanitizer.additionalblacklist -v "attribute1@element1,attribute2@element1, attribute3@element1"
  

• Do not allow protocol1. Colon(:) at end indicates it is a protocol.

  iwcadmin -o mail.htmlsanitizer.additionalblacklist -v "protocol1:"
  

For example:

iwcadmin -o mail.htmlsanitizer.additionalblacklist  -v "@source,srcdoc@iframe,ftp:"

With this settings, HTML element source, srcdoc attribute of HTML element iframe, and ftp protocol will not be allowed in the mail content.

The following example shows a sample configuration using the additional whitelist:

• Allow attribute1 and attribute2 on all elements

• iwcadmin -o mail.htmlsanitizer.additionalwhitelist -v "attribute1, attribute2"
  

• Allow attribute1 on element1 only.

  iwcadmin -o mail.htmlsanitizer.additionalwhitelist -v "attribute1@element1"
  

• Allow element1 and element2.

  iwcadmin -o mail.htmlsanitizer.additionalwhitelist -v "@element1,@element2"
  

• Allow element1. Allow attribute1 on any element. Allow attribute2 on element2.

  iwcadmin -o mail.htmlsanitizer.additionalwhitelist -v "@element1,attribute1, attribute2@element2"
  

• Allow attribute1, attribute2 and attribute3 on element1.

  iwcadmin -o mail.htmlsanitizer.additionalwhitelist -v "attribute1@element1,attribute2@element1, attribute3@element1"
  

• Allow protocol1. Colon(:) at end indicates it is a protocol.

  iwcadmin -o mail.htmlsanitizer.additionalwhitelist -v "protocol1:"
  

For example:

iwcadmin -o mail.htmlsanitizer.additionalwhitelist  -v "testattr2@div, abc:"

With this settings, testattr2 (custom attribute) of HTML element div, and protocol abc (custom protocol) will be allowed in the mail content.

Note:

For additionalwhitelist and additionalblacklist, if an attribute is specified without an associated element, then that attribute will not be allowed on any element.

The following example shows a sample configuration while configuring the additional CSS properties for whitelist:

iwcadmin -o mail.htmlsanitizer.additionalCSSwhitelist -v "item_1,item_2"

where item is a CSS property like visibility and z-index.

Note:

Only few additional CSS properties can be added to the whitelist. You can check the logs to identify the unsupported CSS property and remove it from the whitelist.

Convergence allows the URLs in inline styles in email messages. This can be set by using the mail.htmlsanitizer.allowurlsinstyle parameter. Enabling this option is vulnerable to XSS. This option should be enabled only when the URL referenced in the email message is from trusted source and is secure.

In this example, the image.png displays in the email message when mail.htmlsanitizer.allowurlsinstyle is set to true:

<span style="background-image: url(http://example.com/image.png)"></span>

Enabling Anti-Spam

You can configure Convergence to take action against spam messages in the following ways:

• By setting the anti-spam related parameters in Convergence

• By integrating a spam filter in Messaging Server in addition to setting the anti-spam related parameters in Convergence

Configuring Convergence to Combat Spam

Set the following parameters in Convergence:

• mail.spam.enableaction: Set this parameter to true to enable the anti-spam functionality. Setting this parameter will enable users to take action against spam messages.

  iwcadmin -o mail.spam.enableaction  -v true
  

• mail.spam.folder: Set this parameter to the folder name into which spam messages should be moved.

  iwcadmin -o mail.spam.folder -v SpamFolder
  

You must restart the Oracle certified application server after making the configuration changes.

When you set the parameters, the following spam related functionality is enabled in the Convergence client:

• A system folder is made available as the designated spam folder. This is based on the value set for the mail.spam.folder parameter assigned by the administrator.

• Users will be able to mark messages as spam or not spam. Messages marked as spam are moved into the designated spam folder and messages that are marked as not spam are moved into the Inbox.

Configuring Messaging Server to Combat Spam

A more effective way to counter spam messages is to deploy a spam filer at the back-end Messaging Server in addition to enabling the anti-spam functionality in Convergence. For information on how to integrate a spam filter with the Messaging Server, see the Messaging Server documentation.

After integrating the spam filter, set the value of the service.feedback.spam parameter in Messaging Server to the email address at which spam reports are accepted.

configutil -o  service.feedback.spam -v email_address

When you set this parameter, the following spam related functionality will be available to the Convergence client.

• Users will be able to mark messages as spam. When users mark a message as spam, the message is flagged in the message store, and forwarded to the email address set for the service.feedback.spam configuration utility option. The spam messages are marked in the message list and displayed with a warning in the message viewer.

• Users will be able to mark messages incorrectly identified as spam, as not spam. When the user marks incorrectly identified spam messages as not spam, the flag is removed from the message in the message store.

If Messaging Server is configured with a spam filter that accepts reports of messages that are incorrectly identified as spam, set the value of the parameter service.feedback.notspam to the email address at which Convergence will forward the messages marked as not a spam.

configutil -o service.feedback.notspam -v email_address

Note:

You must restart Messaging Server after making these configuration changes.

Disabling Rich Text Formatting

You can disable rich text formatting in Convergence. When rich text formatting is disabled, email messages are sent in plain text.

To disable rich text formatting, set the client.enablertfcompose configuration property to false. By default, this parameter is set to true. For example:

iwcadmin -o client.enablertfcompose -v false