Previous: Up: Deployment GuideNext:

SMTP Agent WebService Configuration

WebService configuration for the SMTP protocol consists of an retrieving configuration parameters for both the SMTP agent and the security and trust agent from the configuration service. The configuration service exposes a web interface using the WSI basic profile (i.e. SOAP over HTTP) and can be accessed using a simple URL. Example:

	http://myserver/config-service/ConfigurationService

Many configuration settings is persisted in the config-store implementation of the web service, typically in a database. Unlike the XML configuration where settings are managed by editing raw XML, the settings in the web service are configuration via tooling through a web application.

Several aspects of the SMTP agent from domains to certificate storage locations can be configured through configuration web UI. Certificates, trust anchors, and trust bundles themselves can be stored in the configuration service and accessed through the web service interface.

Configuration or the SMTP agent is separated into five components, however they are related to each other:

Domains, certificates, trust anchors, and trust bundles have specific configuration elements stored in the settings component.

Trust Bundles

Trust bundles are a collection of trust anchors that are intended to represent a trust community and generally meet a common set of criteria to be included in the bundle. Trust bundles are packaged into a single file using the PKCS7 standard and distributed via a known URL (the location is discovered out of band). Trust bundles are configured in the Trust Bundles tab of the configuration UI tool.

The Java reference implementation treats bundles as wholistic objects and does not support exclusion of anchors within the bundle. This is partly because the definition of a bundle indicates that each anchor within the bundle meets the same minimal requirements. The decision to include a bundle becomes a simple binary decision, you either trust the bundle or you don't.

Bundles are configured separately from domains as opposed to the importing of anchors per domain (as you will see in the next section). Each bundle is identified by a name and its URL.

To add a trust bundle, click the Add New Bundle link from the configuration UI TrustBundles tab.

The Add New Trust Bundle dialog will display waiting for you enter in the following information:

Once the bundle has been added, it will appear in the table of bundles; however, some of the fields will be empty. This is because the bundle is downloaded from the provided URL in the background and information is updated in the table at a later time.

If the bundle is successfully downloaded and optionally validated, the table will be updated (you may need to click on another tab and come back to the trust bundle tab to see the updates).

The table contains the following information:

ColumnDescription
Bundle NameThe bundle name
URLThe URL where the bundle is downloaded from
ChecksumA SHA1 hash of the bundle
Created
Current As OfThe date when the bundle was last updated in the system
Last RefreshThe date and time when the system last checked for an update. If a newer/different bundle was found, the Current As Of date is also updated. If not updates were found, then the Current As Of date does not change.
Refresh IntervalHow often (in hours) updates are automatically check

If you would like to see the anchor within a bundle, simply click the View Anchors link under the bundle name. This will display a list with the Distinguished Name of each anchor.

To remove a bundle from the system, check the box next to the name of each bundles that you want to remove and click the Delete button. If you delete a bundle that has been associated to a domain, the association is automatically removed.

During the operation of your HISP, it may be necessary to updated bundles in between their configure refresh cycle. To manually refresh/update a bundle, check the box next to the name of the bundles you want to update. The update operation is a background procedure, so the information in the table will not be updated immediately. You may need to click on another tab and come back to the trust bundle tab to see updates.

Domains

The domains component describes the list of domains that will be managed by the agent. Domains are created and maintained in the configuration UI tool.

To create a new domain, click the new Create New Domain link from the configuration UI Manage Domains tab (the first page after logging in).

Each domain requires the domain name and an option postmaster address. Enter the domain name, postmaster address, set the status to enabled, and click add. Optionally, trust bundle can be added at this time by clicking Select Trust Bundles. If you choose not to add bundles at this time, you may do so later. NOTE If the postmaster address is not specified, the SMPT Agent will default it to postmaster@<domain name>.

Anchors

Anchors define the certificates that create trust between domains.

Each domain must have at least one outgoing or incoming trust anchors. Anchors can be retrieved from different source mediums including the configuration service. The anchor storage medium is configured in the settings page of the configuration UI. All settings are configured as simple name/value pairs.

Anchor Store Settings

SettingDescription
AnchorStoreTypeThe storage type of the anchor store. Valid types:

WS (default): Anchors are stored in the configuration service.
LDAP: Anchors are stored in an LDAP server.
KEYSTORE: Anchors are stored in a local keystore file.
AnchorResolverTypeThe type of the anchor resolver. Valid types:
Uniform: All domains use the same anchors for all addresses.
Multidomain: Each domain defines its own discrete set of trust anchors.
AnchorKeyStoreFileFor keystore store types, the name of the file that contains the certificates. This can be just a file name, a fully qualified path, or a relative path.
AnchorKeyStoreFilePassFor keystore store types, an optional password used to encrypt the file.
AnchorKeyStorePrivKeyPassFor keystore store types, an optional password used to encrypt private keys.
TrustAnchorLDAPUrlFor LDAP store types, the url to the LDAP server. Consists of the protocol, host, and port. Multiple URLs can be define and are comma delimeted. Example: ldap://somehost:389
TrustAnchorLDAPUserFor LDAP store types, the user name credential for connecting to the LDAP store. May be empty if the LDAP server allows anonymous binding.
TrustAnchorLDAPPasswordFor LDAP store types, The password credential for connecting to the LDAP store.
TrustAnchorLDAPConnTimeoutFor LDAP store types, an optional timeout in seconds before the connection is failed.
TrustAnchorLDAPSearchBaseFor LDAP store types, the distinguished name used as the base of LDAP searches.
TrustAnchorLDAPSearchAttrFor LDAP store types, the attribute in the LDAP store that is used to match a search query.
TrustAnchorLDAPCertAttrFor LDAP store types, the attribute in the search query result that holds the certificate file.
TrustAnchorLDAPCertFormatFor LDAP store types, the format of the certificate in the LDAP store. Valid formats: pkcs12, X.509
TrustAnchorLDAPCertPassphraseFor LDAP store types and pkcs12 files, the pass phrase used to encrypt the certificate.

Web Service Anchor Storage

Anchors stored in the configuration service are added and maintained in the Anchors tab of the configuration service Manage Domains page.

The certificate field is the location of the DER encoded certificate file that represents the trust anchor. Incoming and outgoing indicates if the trust anchor should be used for incoming or outgoing anchors. Clicking Add Anchor will add the anchor to the domain indicated by the Domain Name field and upload the anchor to the configuration service.

Non Web Service Anchor Storage

Anchors stored in now web service mediums such as LDAP or a keystore require a list of aliases or search criteria to locate the certificates in the anchor store. Each domain requires on of two entries in the settings component: one for a list of outgoing anchors and/or one for a list of incoming anchors. The settings use the following format:

  • <domainName>IncomingAnchorAliases
  • <domainName>OutgoingAnchorAliases

The value for each setting is a comma delimited list of the aliases or search criteria that identify the anchor in the anchor store. The following example would be used for an LDAP anchor store:

  • cerner.com,securehealthemail.com,microsoft.com

Example settings for the domain cerner.com using an LDAP store:

Setting NameValue
cerner.comIncomingAnchorAliasescerner.com,securehealthemail.com,microsoft.com
cerner.comOutgoingAnchorAliasescerner.com,securehealthemail.com,microsoft.com

NOTE Regardless of the storage mechanism, a domain should always add its own trust anchor to its list or trusted anchors. This is a security precaution to ensure only users with valid certificates signed by the trust anchor can send from the agent's managed domain(s).

Trust Bundles

Configured trust bundles can be added to a domain from the Trust Bundles tab of the configuration service Manage Domains page. Each anchor in the bundle is used to create trust between the domain and the system represented by the anchor. Similar to configuring anchors, each bundle can be set to incoming or outgoing to control the direction of trust.

To associate one or more bundles to a domain, click the Assign Additional Trust Bundles link. Select each bundle and select if the bundle should be incoming, outgoing, or both.

PublicCertStore

Similar to anchors, public certificates can be retrieved from different source mediums. The public certificate storage medium is configured in the settings page of the configuration UI.

Public Certificate Store Settings

SettingDescription
PublicStoreTypeThe storage type of the public certificate store. Valid types:

DNS: Certificates are resolved using DNS.
KEYSTORE: Certificates are stored in a local keystore file.
WS: Public certificates are stored in the configuration service.
PublicLDAP: Certificates are resolved from publicly accessible LDAP servers. LDAP servers are resolved dynamically using DNS SRV.

In some cases, multiple store types may be necessary to resolve a public certificate. For example some HISPs use DNS to distributed public CERT while others may use out of band processes and require a HISP to manually import the CERT(s) into the storage medium. Multiple store types are separated by a comma (,).

Default Value: DNS,PublicLDAP
PublicStoreFileFor keystore store types, the name of the file that contains the certificates. This can be just a file name, a fully qualified path, or a relative path.
PublicStoreFilePassFor keystore store types, an optional password used to encrypt the file.
PublicStorePrivKeyPassFor keystore store types, an optional password used to encrypt private keys.

PrivateCertStore

The private certificate storage medium is configured in the settings page of the configuration UI.

Private Certificate Store Settings

SettingDescription
PrivateStoreTypeThe storage type of the private certificate store. Valid types:

WS (default): Certificates are stored in the configuration service.
LDAP: Certificates are stored in an LDAP server.
KEYSTORE: Certificates are stored in a local keystore file.
PrivateStoreFileFor keystore store types, the name of the file that contains the certificates. This can be just a file name, a fully qualified path, or a relative path.
PrivateStoreFilePassFor keystore store types, an optional password used to encrypt the file.
PrivateStorePrivKeyPassFor keystore store types, an optional password used to encrypt private keys.
PrivateStoreLDAPUrlFor LDAP store types, the url to the LDAP server. Consists of the protocol, host, and port. Multiple URLs can be define and are comma delimeted. Example: ldap://somehost:389
PrivateStoreLDAPUserFor LDAP store types, the user name credential for connecting to the LDAP store. May be empty if the LDAP server allows anonymous binding.
PrivateStoreLDAPPasswordFor LDAP store types, The password credential for connecting to the LDAP store.
PrivateStoreLDAPConnTimeoutFor LDAP store types, an optional timeout in seconds before the connection is failed.
PrivateStoreLDAPSearchBaseFor LDAP store types, the distinguished name used as the base of LDAP searches.
PrivateStoreLDAPSearchAttrFor LDAP store types, the attribute in the LDAP store that is used to match a search query.
PrivateStoreLDAPCertAttrFor LDAP store types, the attribute in the search query result that holds the certificate file.
PrivateStoreLDAPCertFormatFor LDAP store types, the format of the certificate in the LDAP store. Valid formats: pkcs12, X.509
PrivateStoreLDAPCertPassphraseFor LDAP store types and pkcs12 files, the pass phrase used to encrypt the certificate.

Web Service Private/Public Certificate Storage

Private and public certificates stored in the configuration service are added and maintained in the Manage Certificates page of the configuration service application.

The certificate field is the location of the DER encoded certificate file that represents the private or public certificate. Clicking Add Certificate will add the certificate to the configuration service. NOTE The owner is automatically populated by the service when the certificate is added.

NOTE: Private certificate files should be pkcs12 encoded files with no encryption on both the file and private key stored in the file. Although pkcs12 files can be created from open source tools such as openssl, the Java Reference implementation agent module contains a tool for creating pkcs12 files in the expected format from DER encoded X509 certificates and pkcs8 DER encoded private key files. It also contains a tool for stripping encryption from existing pkcs12 files.

XXMessageSettings

The following settings describes the location where processed messages should be stored. This is intended for debug purposes only and should not be set in a production environment.

MessageTypes:

SettingDescription
RawMessageSaveFolderThe folder where raw messages will be stored. If the folder does not exist, the system will automatically created it as long as the agent's process has permission to do so.
OutgoingMessageSaveFolderThe folder where outgoing messages will be stored. If the folder does not exist, the system will automatically created it as long as the agent's process has permission to do so.
IncomingMessageSaveFolderThe folder where incoming messages will be stored. If the folder does not exist, the system will automatically created it as long as the agent's process has permission to do so.
BadMessageSaveFolderThe folder where bad messages will be stored. If the folder does not exist, the system will automatically created it as long as the agent's process has permission to do so.

MDN Settings

The agent automatically produce MDN message for all successfully processed messages with a disposition of Processed. MDN is described in RFC3798 and is intended (for the SMTP Agent purposes) to indicate the successful reception and processing of message by the security and trust agent.

SettingDescription
MDNAutoResponseIndicates if the SMTP agent should produce MDN messages for MDN requests. The default setting is true if this attribute is not present.
MDNProdNameThe product name used in the user agent header of the MDN message. Defaults to Security Agent if this attribute is not present.
MDNTextHuman readable response text sent back to the sender indicating a successful reception of the senders message.


Previous: Up: Deployment GuideNext: