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

All configuration information is stored in the implementation of the web service, typically in a database. Unlike the XML configuration where settings are managed by editing raw EXML, the settings in the web service are configuration via tooling through a web application.

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

Configuration is separated into four components, however they are related to each other:

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

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 domain button from the configuration UI domain search page (the first page after logging in).

Each domain requires the domain name and a postmaster address. Enter the domain name, postmaster address, set the status to enabled, and click add.

Anchors

Anchors define the certificates that determine trust between domains.

Each domain must have at least one outgoing and 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 domain page.

The certificate field is the file 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 domain indicated by the owner 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 two entries in the settings component: one for a list of outgoing anchors and 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).

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 (default): Certificates are resolved using DNS.
KEYSTORE: Certificates are stored in a local keystore file.
WS: Public certificates are stored in the configuration service.

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 (,).
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 certificates stored in the configuration service are added and maintained in the Certificates tab of the configuration service domain page.

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

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.

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 can automatically produce MDN message in response to MDN requests 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 false 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: