SetSecurity

Defines the security context for connecting to an SMTP or POP3 server using a security driver.

"UPOPMAIL".SetSecurity(DriverProperties, DriverParameters)

Example: activate "UPOPMAIL".SetSecurity("SMTP=UAuthLoginSMTP;Use=Mand", "user=pjones;password=mys3cret")

Parameters

DriverProperties

Uniface list that specifies a security driver for authenticating the connection to a POP or SMTP server, with the following syntax:

"ServerType=EntryPointFunction {;USE=MAND | OPT}"

  • ServerType—one of POP or SMTP. The keyword can be upper or lowercase.
  • EntryPointFunction—function that implements a security driver and establishes a security context for the connection. The function name is case sensitive. For the security drivers provided by Uniface, one of:
    • For SMTP:

      UStartTLSSMTP
      UAuthXOAUTH2SMTP
      UAuthNTLMSMTP
      UAuthLoginSMTP
      UAuthSSPISMTP

    • For POP: UAuthXOAUTH2POP
  • USE—indicates whether use of this driver is mandatory or optional. The keyword and values may be upper or lower case.
    • MAND—mandatory (default); if the server does not support it, an error is returned.
    • OPT—optional; used only in the initial check for supported authentication method.

    When a driver is about to be used in an SMTP or POP3 logon, Uniface first checks that the authentication method is supported. If OPT is specified and it is not supported, the driver is ignored and is not used. If it is supported and is used and fails, an error is returned, whether or not OPT is specified.

If this parameter contains only "SMTP=" or "POP=", the security context is removed. Maximum size is 255 bytes.

DriverParameters

Uniface list containing driver-specific parameters that are used during authentication. These normally include:

"user=UserName ;{password=Password | token=AccessToken} {;OtherParameters}"

Maximum size is 4095 bytes.

For information on specific driver parameters, consult the security driver documentation. For the security drivers provided by Uniface, see:

Return Values

Value Returned by $status
Value Meaning
0 Success
-1 Security driver initialization error
-2 Invalid properties keyword or value
-3 Not allowed to change context in a connection lifetime
-4 Could not get access to Uniface
-5 Could not find entry point function
-6 Memory allocation error

Use

The SetSecurity operation can be used to add security drivers to a security context or to remove the context completely. It can only be called before a call to the following operations:

  • LogonMail
  • LogonSMTP
  • SendMail

or after a call to:

  • LogoffMail
  • LogoffSMTP
  • SendMail.

Description

Security drivers perform an initial exchange of messages when a connection is established to an email server. This exchange of messages normally implements an authentication process, which determines whether this user is allowed to use the server. Uniface provides several security drivers that implement different authentication protocols. For more information, see Security Drivers for Email Authentication.

The SMTP STARTTLS security driver is slightly different in that it upgrades an initial TCP connection to TLS. This is required for SMTP servers that use the STARTTLS protocol instead of supporting a direct initial TLS connection.

For examples of how SetSecurity can be used, see Using Email Security Drivers.

Defining the Security Context

The security context is the complete security environment required for a secure connection to an email server. For more information, see Security Context.

The SetSecurity operation adds a security driver to the security context of a particular connection to an email server, for the duration of the connection lifetime. Each subsequent call to SetSecurity adds a security driver to the context. Each security driver is called in turn to establish the security context when a new connection is created to the mail server.

The security context lasts for the duration of the connection's lifetime, and starts with a call to one of the UPOPMAIL operations LogonMail, or LogonSMTP, or SendMail.

Note:  As the programmer, it is your responsibility to ensure that the context that is established is valid.

To remove all security mechanisms, call the SetSecurity operation with no driver details, that is the DriverProperties string contains "SMTP=" or "POP=".

Connection Lifetime

For SMTP, a connection lifetime is the duration of one SendMail call or the time between a LogonSMTP and a LogoffSMTP call.

For POP, a connection lifetime is the time between a LogonMail and LogoffMail call

The SetSecurity operation must be called before a connection lifetime and applies to all subsequent connections made using that UPOPMAIL instance. There is no need to call SetSecurity before each LogonSMTP or LogonMail call.

After a connection lifetime, calls to SetSecurity create a completely new security context. There is no need to explicitly remove the previous context first. However, if you wish to remove an existing context from an instance, call SetSecurity with only the ServerType keyword, for example SetSecurity("SMTP=","").

Calling SetSecurity during a connection lifetime returns an error. If a call to SetSecurity fails, the previously established security context remains in the same state that it was before the error occurred.

Related Topics