PMDF System Manager's Guide

The format of the PMDF security configuration file is similar to that of the PMDF Service Dispatcher configuration file or the PMDF Job Controller configuration file. That is, the PMDF security configuration file generally contains lines of the form

option=value

in accordance with the format of PMDF option files.

In addition to such option settings, the file can contain a line consisting of a section and value enclosed in square brackets of the form

[AUTH_SOURCE=auth-source-name]

or

[RULESET=security-rules-set-name]

or

[USERNAME_TRANSLATE=translation-type-name]

or

[PROP_SOURCE=auxiliary-property-name]

or

[CLIENT_AUTH=auth-name]

An AUTH_SOURCE section defines an authentication source and sets options for that source. It is not necessary to include an AUTH_SOURCE section for predefined authentication sources, unless a site wants to set special options for that source or unless the source is one such as LDAP which has special required options. If a site wants to provide their own authentication sources, an AUTH_SOURCE section defining that source is required.

A RULESET section sets options applying only to the specified sorts of connections. The value of security-rules-set-name is either DEFAULT, or a security rule set selected via the PORT_ACCESS mapping; see Section 14.3. Note that the vertical bar character, |, is not permitted in a security-rules-set-name.

If a site, via the PORT_ACCESS mapping, sorts connections into security rule sets other than the default rule set, DEFAULT, then the site's security configuration file should have a RULESET section for each such security rule set, describing the authentication rules to use for connections falling into that security rule set.

A USERNAME_TRANSLATE section defines a username translation function. It is not necessary to include a USERNAME_TRANSLATE section for a predefined username translation function. If a site wants to provide their own username translation function, then a USERNAME_TRANSLATE section defining that function is required. See Section 14.2.5 below.

A PROP_SOURCE section defines an authentication plug-in, referred to as an auxiliary properties module, that can fetch per-user attribute values, "auxiliary properties", during the user authentication process; this tends to be of interest to improve efficiency by getting such attributes directly from the authentication source. See Section 14.2.6 below.

A CLIENT_AUTH section sets options for use by the SMTP client when authenticating to a remote SMTP server. The value of auth-name is either DEFAULT or a name selected via the client_auth channel keyword. If a site, via the client_auth keyword, uses more than one set of client authentication information, then the site's security configuration file should have a CLIENT_AUTH section for each such set.

The following general options can be specified in the PMDF security configuration file.

AUTH_METHOD (1 or 2)

This option controls PMDF's behavior when authenticating usernames and passwords against the list of authentication sources and mechanisms specified in an ENABLE option. The default value is 1, which causes PMDF to check each source/mechanism pair from left to right, stopping as soon as it gets a definitive answer, either pass or fail. A value of 2 causes PMDF to keep checking authentication sources until it gets a pass result, or until all sources are exhausted. Specifically, this option changes PMDF's behavior when getting a fail result: the default behavior is to stop, while a value of 2 causes PMDF to keep going.

AUXPROP_ENABLE (comma-separated list of auxiliary-property-modules)

This option, when set in a RULESET section, specifies a list of auxiliary property modules to utilize to set auxiliary properties during authentication. Certain auxiliary properties are available from some authentication sources. Or additional auxiliary properties can be made available by site-supplied auxiliary property modules defined via PROP_SOURCE sections.

BASEDN (distinguished-name)

This option must be used in an [AUTH_SOURCE=LDAP] authentication source definition section to specify the point of the Directory Information Tree to which to bind.

ENABLE (comma-separated list of source/mechanism pairs)

This option specifies a comma separated list of mechanisms to enable. Each item includes the source name, a slash character, /, and a mechanism name. The source name should either be one of the predefined authentication source names (ANONYMOUS, LDAP, LOGIN, MSGSTORE, PASSDB, POPPROXY, or SYSTEM) or a site-supplied authentication source, as described in Section 14.2.3. The possible mechanism values will vary according to the particular authentication source; for instance, among the predefined authentication sources, the ANONYMOUS source supports only the ANONYMOUS mechanism; the LDAP source supports the PLAIN and CRAM-MD5 mechanisms; the POPPROXY and SYSTEM sources support only the PLAIN mechanism; while the PASSDB and MSGSTORE sources support any of APOP, CRAM-MD5, DIGEST-MD5, or PLAIN. (For further details on these predefined authentication mechanisms, see Section 14.2.4.) Site-supplied authentication sources can have their own list of supported mechanisms. The asterisk character *, can be used to refer to all mechanisms supported by that authentication source. For instance,

ENABLE=SYSTEM/PLAIN,MSGSTORE/*

If the list of source/mechanism pairs includes more than one source supporting a particular mechanism, then the order of the source/mechanism pairs in the list is significant. When verifying with a particular mechanism, the first source (reading from left to right) that supports that mechanism will be checked first for an entry; if no entry is found, then the next source (reading from left to right) that supports that mechanism will be checked for an entry, etc. By default, the verification process is halted as soon as one of the authentication sources provides a definitive answer: PASS or FAIL. This behavior can be modified. If the AUTH_METHOD option is specified with a value of 2, PMDF will continue checking sources until it gets a PASS result (or until all sources are exhausted). That is, a FAIL result will no longer cause PMDF to stop checking.

FUNCTION (entry-point)

IMAGE (logical-pointing-to-shared-image (OpenVMS) or shared-image-name (UNIX) or dynamic-link-library (NT))

In an AUTH_SOURCE authentication source definition section defining a site supplied authentication source, the IMAGE option specifies the shared image to use and the FUNCTION option specifies the entry point. These options are mandatory for site defined authentication source definition sections. In a USERNAME_TRANSLATE section defining a site-supplied translation function to be applied to usernames prior to authentication, the IMAGE option specifies the shared image to use and the FUNCTION option specifies the entry point. The IMAGE option is mandatory for site defined username translation functions. The FUNCTION option can be omitted if the entry-point is called sasl_canonuser_init. In a PROP_SOURCE section defining a site-supplied authentication auxiliary properties module, the IMAGE option specifies the shared image to use and the FUNCTION option specifies the entry point. The IMAGE option is mandatory for site defined authentication auxiliary property modules. The FUNCTION option can be omitted if the entry-point is called sasl_auxprop_init. On OpenVMS, the value of the IMAGE option must be a system, executive mode logical name that translates to the name of the shared image; on UNIX, the value of the IMAGE option must be the name of the shared image file; on NT, the value of the IMAGE option must be the name of a dynamic link library (DLL).

LDAP_ATTRIBUTE (attribute-name)

This option can be used in an [AUTH_SOURCE=LDAP] authentication source definition section to specify the name of the attribute to use. The default if this option is not specified is "uid". If the LDAP server that you are using is Active Directory, this option should be specified with a value of "sAMAccountName".

LDAP_CACERTFILE (file-name)

This option can be used in an [AUTH_SOURCE=LDAP] authentication source definition section to specify the name of the file containing the Certificate Authority (CA) certificate that should be used. This option is optional. The default if this option is not specified is to look for the default CA certificate file pmdf_table:ldap-cacert.pem.

LDAP_SEARCHACCT_DN (distinguished-name)

LDAP_SEARCHACCT_PASSWORD (password)

By default, PMDF does an anonymous bind to the LDAP server in order to search it for the username to authenticate. Some LDAP servers, such as Active Directory, do not allow anonymous binds. Use these two options to specify a distinguished name and password to use for that binding process. Only used in an [AUTH_SOURCE=LDAP] authentication source definition section.

LDAP_TLS_MODE (1 or 2)

This option can be used in an [AUTH_SOURCE=LDAP] authentication source definition section to specify whether to use TLS. A value of 1 tells PMDF to try to use TLS, but continue without it if TLS is not available. A value of 2 tells PMDF to require TLS. The default is to not use TLS.

LDAP_VERSION (2 or 3)

This option can be used in an [AUTH_SOURCE=LDAP] authentication source definition section to specify the type of LDAP server in use, v2 or v3, and hence the type of query to perform.

MAIL_DOMAIN (domain-name)

When the LOCALMAIL auxiliary properties module is in effect (explicitly, or implicitly because the PASSDB or SYSTEM authentication source is used), then the auxiliary property SASL_AUX_MAILADDR is normally set to the authenticating username plus the official local host name (PMDF local channel official host name). This option can be used to specify an alternate domain name to use in this auxiliary property.

MECHANISMS (comma separated list of mechanisms)

This option, when used in a CLIENT_AUTH section, specifies which SASL mechansims to use when an SMTP client is authenticating to a remote SMTP server. The possible mechanisms values are: PLAIN, LOGIN, CRAM-MD5, and DIGEST-MD5. If this option is not specified, all mechanisms are tried.

PASSWORD (string)

This option, when used in a CLIENT_AUTH section, specifies the password to use when an SMTP client is authenticating to a remote SMTP server. This option is required in a CLIENT_AUTH section.

RESTRICT (string)

This option can be used as, for instance, RESTRICT=PLAIN:40 to require a key with 40 significant bits be used for encryption before the PLAIN mechanism is allowed.

SERVER (host-name or ip-number)

This option is used in an [AUTH_SOURCE=LDAP] or [AUTH_SOURCE=POPPROXY] section to specify the LDAP server or POP server, respectively, to which to connect for authentication. The syntax is

SERVER=server-host-name:port

or

SERVER=server-host-name

where the port number if omitted will be assumed to be the standard port number (389 for LDAP, or 110 for POP). For POPPROXY, there can be up to three POP servers specified, separated by commas.

TLS_MODE (0 or 1)

This option can be used in an [AUTH_SOURCE=POPPROXY] authentication source definition section to specify whether to use TLS. A value of 1 tells PMDF to try to use TLS. The default is to not use TLS.

TRANSLATE (translation-type-name)

This option can be used in a RULESET section to specify a function to be appled to usernames before authentication; that is, the username provided by the user attempting to authenticate will be transformed as specified by the function and PMDF will use that transformed username when attempting the authentication. The translation type name must either be one of the predefined translation functions, DEFAULT, ASCII-NOCASE, or IDENTITY, or must specify a translation type name defined in a USERNAME_TRANSLATE section.

USER (username)

This option, when used in an [AUTH_SOURCE=ANONYMOUS] authentication source section, determines the specific username under which anonymous authentication can be performed. When this option is used in a CLIENT_AUTH section, it specifies the remote username to use when an SMTP client is authenticating to a remote SMTP server. This option is required in a CLIENT_AUTH section.

The following additional transition-related options can also be specified in the PMDF security configuration file.

TRANSITION_ADD (comma-separated list of source/mechanism pairs)

This specifies a list of mechanisms to add when a transition occurs.

TRANSITION_CRITERIA (CLIENT, CHANGE, PLAIN)

This specifies the criteria used to transition users. CHANGE will only transition on password change. CLIENT will transition if the client attempts to use a mechanism for which they don't have a proper entry. Note that in such a case, where the client does not actually have a password entry for the desired mechanism, the server will ask the client to authenticate themselves using a plaintext password (authenticating against the configured authentication source) and the server will then automatically create the desired mechanism entry in that authentication source using the same password value. PLAIN will transition whenever the client uses a plaintext password. The default is TRANSITION_CRITERIA=CHANGE.

TRANSITION_DELETE (comma-separated list of source/mechanism pairs)

This specifies a list of mechanisms to delete when a transition occurs. Not all authentication sources support this. This option will not take effect unless a TRANSITION_RETAIN_USERS option is present.

TRANSITION_DISABLE (comma-separated list of source/mechanism pairs)

This specifies a list of mechanisms to disable when a transition occurs. Not all authentication sources support this. This option will not take effect unless a TRANSITION_RETAIN_USERS option is present.

TRANSITION_FROM (comma-separated list of source/mechanism pairs)

This specifies a list of authentication sources to check when transitioning, in addition to those listed in the ENABLE configuration item. Normally, a user must use one of the source/mechanisms enabled via the ENABLE option in order to connect at all. With the TRANSITION_FROM option, PMDF can be configured to allow one-time-only connection using some other source/mechanisms in order to perform the transition to one of the supported (enabled) source/mechanisms. For instance, when a site is setting up new PMDF MessageStore accounts, one might want to configure IMAP and POP service to require authentication using a user's PMDF user profile password (i.e., PMDF MessageStore password). However, if the first time the user connects they do not yet have a PMDF user profile password set, then allow them to connect using their system password, which will automatically become their initial PMDF MessageStore password. This would correspond to:

[RULESET=IMAP-RULES] ENABLE=MSGSTORE/* TRANSITION_CRITERIA=CLIENT TRANSITION_FROM=SYSTEM/PLAIN TRANSITION_ADD=MSGSTORE/APOP ! [RULESET=POP-RULES] ENABLE=MSGSTORE/* TRANSITION_CRITERIA=CLIENT TRANSITION_FROM=SYSTEM/PLAIN TRANSITION_ADD=MSGSTORE/APOP

assuming that a PORT_ACCESS mapping is in use that sorts IMAP and POP connections into their own rulesets.

TRANSITION_RETAIN_USERS (comma-separated list of user usernames)

This specifies a list of users who are exempt from the TRANSITION_DISABLE and TRANSITION_DELETE options. This option must be set---even if only to an empty value---in order for the TRANSITION_DISABLE and TRANSITION_DELETE options to take effect. That is, TRANSITION_RETAIN_USERS= is fine.