SMTP STARTTLS Security Driver

The SMTP STARTTLS security driver upgrades the default TCP connection to TLS by means of the STARTTLS extension. It must be the first driver to the security context using the SetSecurity operation of the UPOPMAIL component:

activate"UPOPMAIL".SetSecurity(DriverProperties", "")

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

Parameters

For SetSecurity:

  • DriverProperties—Uniface list specifying the SMTP security driver and whether its USE is mandatory or optional:

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

  • DriverParameters—there are no driver parameters for the STARTTLS driver so this parameter should be an empty string. The user name and password (or token) will be supplied by another driver in the security context.

For GetSecurity :

  • DriverNumber—number of the driver in the security context; usually 1.
  • "SMTP="—returns the DriverProperties string as used in the SetSecurity operation.
  • RuntimeInfo—Uniface list containing information provided by Uniface. The STARTTLS driver does not provide extra runtime information.

Description

The STARTTLS security driver enables UPOPMAIL to upgrade an SMTP session from an initial plain TCP connection to a more secure TLS connection. If the SMTP server requires authentication, a second supported authenticating driver should be added to the security context. Both security drivers must be defined as part of the security context using the UPOPMAIL SetSecurity command.

The UPOPMAIL LogonSMTP is used to initiate the connection to the SMTP server. When this is executed:

  1. The UPOPMAIL component opens the initial connection over TCP and gets the list of supported features.
  2. The STARTTLS security driver examines the server’s supported extensions, and when it sees that it supports STARTTLS, issues the STARTTLS command, and upgrades the connection to TLS using the default TLS profile specified by the usys$TLS_params setting.
  3. The UPOPMAIL component sees that there are more drivers in the security context and gets the list of supported features again, which has now changed because of the upgrade to TLS.
  4. The next security driver then also examines the extensions. If the security driver recognizes itself as being supported (it is verified), it will be used. This will normally do the authorization.

Calling a STARTTLS Security Driver from UPOPMAIL

The TLS connector must be configured using USYS$TLS_PARAMS. For more information, see TLS Connector and TLS Connector Options. For example:

[DRIVER_SETTINGS]
USYS$TLS_PARAMS verify_server=1, ca_certificate=cacert.pem, verify_server_name=0

Note: If ca_certificate is omitted, the default certificate is assumed to be ca-bundle.crt, located in the \common\usys directory of your Uniface installation.

The security drivers that will be used by Uniface application need to be specified in the application's assignment file. For example:

[USER_3GL]
InstallDir\common\bin\ustarttls(UStartTLSSMTP)
InstallDir\common\bin\uauthlogin(UAuthLoginSMTP)

The following code shows the basic sequence of steps required to specify the security context and connect to the SMTP server using UPOPMAIL.

variables 
  handle hPopmail
  string vSmtpServer
endvariables 
				
; Create a new UPOPMAIL instance
newinstance "UPOPMAIL", hPopmail

; Define two security drivers in the security context.
; The first will upgrade the initial TCP connection to a TLS connection.
; The second will do an SMTP logon with a username and password, over that TLS connection.
 
hPopmail->setsecurity("SMTP=UStartTLSSMTP;USE=MAND", "")
hPopmail->setsecurity("SMTP=UAuthLoginSMTP;USE=MAND", "USER=john;PASSWORD=s3cret")

; Specify the network connection string to the SMTP server 
vSmtpServer = "smtp.office365.com+587"				
				
; Do the actual connect and logon.
hPopmail->logonsmtp(vSmtpServer, "", "")

For more information, see Using Email Security Drivers.

Related Topics