SMTP SSPI Security Driver

The Uniface SSPI security driver is a Windows-specific driver that enables you to use the NTLM or Kerberos protocols for SMTP authentication. The driver uses the Windows Security Support Provider Interface (SSPI).

activate"UPOPMAIL".SetSecurity(DrvierProperties, DriverParameters)

activate"UPOPMAIL".GetSecurity(DriverNumber, "SMTP=", RuntimeInfo)

Parameters

  • DriverProperties—Uniface list with the following syntax:

    "SMTP=UAuthSSPISMTP {;USE=MAND | OPT"}

  • DriverParameters—Uniface list containing driver-specific parameters that are used during authentication. See Driver Parameters.
  • DriverNumber—number of the driver in the security context; usually 1.
  • "SMTP="—request the DriverProperties string as used in the SetSecurity operation.
  • RuntimeInfo—Uniface list containing information provided by Uniface and the security driver. See Runtime Information Returned.

For more information, see SetSecurity and GetSecurity .

Driver Parameters

Parameters are not case-sensitive.

SSPI Parameters
Keyword Allowed Values Description
SSP Negotiate

NTLM

Kerberos

Specifies the protocol the driver is to use. Mandatory.
SPN_SERVER SMTPSVC/Host.Qualified.Name@KERB.REALM.NAME Service Principal Name of an SMTP server. Mandatory if Kerberos is to be used; otherwise optional.

You need to find out what this name is for your server.

SPN_USER NtlmDomain\User

User@KerberosRealm

Indicates that alternative user credentials will be supplied. Optional. In effect, this acts as a flag that instead of using the credentials of the logged-on user, the credentials specified by USER and PASSWORD will be used.

The general form of the name is also shown.

USER User User name to use for the login. Mandatory if SPN_USER has been used; otherwise, it should not be used.
PASSWORD Password Password to use for the login. Mandatory if SPN_USER has been used; otherwise, it should not be used.
DOMAIN NtlmDomain

KerberosRealm

Domain name or computer name in case of a local user. Mandatory if SPN_USER has been used, otherwise it should not be used.

Runtime Information Returned

The SSPI security driver can return runtime information about the current or last connection for GetSecurity.

Runtime Information Returned by the SSPI Security Driver
Property Description
SSP Provider that was actually used, NTLM or Kerberos
SPN_SERVER Service Principal Name of the SMTP server. Only returned if the provider used was Kerberos.
SPN_USER Service Principal Name of the client user. Only returned if the provider used was Kerberos.
USER User name whose credentials were used by the provider.

Assignment File

To use this driver the assignment file must contain:

[USER_3GL]
Location\uauthsspi(UAuthSSPISMTP)

If the SMTP server can support NTLM but returns an unexpected error after the first message, it may be that the server has a different way of handling the initial message from the client. In this case, try setting NTLM_INITIAL_RESPONSE in the [LOGICALS] section. For example:

[LOGICALS]
NTLM_INITIAL_RESPONSE = Deferred

For more information, see NTLM_INITIAL_RESPONSE.

Description

The compiled library uauthntlm is provided in the \common\bin (Windows) or /common/lib (Unix) directory of your Uniface installation.

The C source files for the security driver are available in the Security Driver Sample on Rocket Community.

This driver uses the GSSAPI interface to negotiate the authentication protocol. Under Windows, this commonly results in the Kerberos authentication protocol. When it applies to Kerberos, it provides the strongest authentication method. AUTH GSSAPI also supports session signing and encryption.

Windows supplies several security providers that this driver can use for authentication.

The Negotiate package tries to determine which protocol is most appropriate, Kerberos or NTLM. This is done on the basis of the optionally supplied SPN_SERVER and user credentials. Both Kerberos and NTLM can use the credentials of the current logged-in user. However, depending on the state and age of the credentials, they may no longer be suitable for Kerberos. It is recommended to supply user credentials and a valid SPN_SERVER to ensure the use of the Kerberos protocol.

Microsoft provides a number of downloadable utilities, such as KERBTRAY.EXE and SETSPN.EXE, that enable you to see the Kerberos tickets you have cached or to create SPN names. A ticket refresh can be achieved, for example, by locking your work station and then unlocking it. The alternative is to provide user credentials to the driver.

Related Topics