Security Context

A security context is the complete security environment required for a secure connection to a mail server. It consists of one or more security drivers that are responsible for connection and authentication to the email server.

The security context is established by calling the SetSecurity operation of the UPOPMAIL component. Each subsequent call to SetSecurity adds a security driver to the security context of a particular connection to an email server, for the connection's lifetime.

The security context can be viewed as a queue of drivers, established in the order of the SetSecurity call. When a connection is established to an SMTP or POP3 server, each driver in the security context queue is called in turn, from beginning to end, to verify that the server supports the functionality that the driver implements. The drivers that are supported are then called in turn to implement that functionality.

In most cases, only one security driver is required in the security context. For example, if two calls are made to SetSecurity specifying the NTLM security driver, the NTLM authentication is attempted twice and will fail.

However, when using the SMTP STARTTLS driver, the process of verification and implementation is split. Once the STARTTLS driver is encountered and has verified that it is supported, the verification process stops. All the drivers in the security context up to and including the STARTTLS driver are then called to implement their functionality.

Once that has been done, the server is again queried as to the feature extensions that it supports. Normally this list of supported features has changed after the upgrade to TLS with some authentication extensions. Then the process of verification and implementation resumes with the remaining drivers in the context.

In practice, this means that the STARTTLS driver would normally be the first driver in the context, followed by an authentication driver such as the AUTH LOGIN or the AUTH XOAUTH2 driver.

Some security mechanisms may allow or require multiple drivers in the security context. When establishing and removing a security context with multiple drivers, note that:

Drivers are called in the order they were added to the context. When removing a context, drivers are called in reverse order.
If one driver in the security context returns an error, the process stops and drivers that have already done their opening protocol are called to perform their closing protocol. When removing a context, errors are effectively ignored and each driver is called.
When connecting to a Microsoft SMTP server, you must first add the STARTTLS driver, followed by another security driver to handle authentication.

For more information, see UPOPMAIL and Security Drivers for Email Authentication.