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]

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.

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

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, 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.

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_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.

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=ldap-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).

SIA_SES_LAUNCH (0 or 1; Tru64 UNIX only)

This option is only available on Tru64 UNIX. On Tru64 UNIX with C2 security, this option affecting the SYSTEM authentication source can be used to specify that PMDF should reset login failure counts for system accounts as follows:

[AUTH_SOURCE=SYSTEM] SIA_SES_LAUNCH=1

Note that setting the SIA_SES_LAUNCH option incurs a performance penalty.

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 can be used in an [AUTH_SOURCE=ANONYMOUS] authentication source section to determine a specific username under which anonymous authentication can be performed.

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.