GAMBAS BOOK 3.19.1

The component enables you to send e-mails using the SMTP protocol. Supported are, among other things, email attachments and optional connection security via SSL or TLS, provided the 'openssl' programme is installed on your system. This component gb.net.smtp is present in all Gambas3 versions since version 3.6 and was written entirely in Gambas .

The SmtpClient class has the following properties:

Table 24.4.0.1.1 : Properties of the SmtpClient class

The constants of the SmtpClient class associated with the Encrypt property are:

• Net.None (0) Without connection security.
• Net.SSL (1) SSL connection security
• Net.TLS (2) TLS connection security

The SmtpClient class has only three methods:

Table 24.4.0.2.1 : Methods of the class SmtpClient

The static method FormatDate ( Date As Date ) As String formats a date according to the syntax of RFC 822: SmtpClient.FormatDate(Now) → Mon, 01 Feb 2016 18:12:36 GMT .

If an SMTP server allows authentication via the CRAM-MD5 (Challenge Response Authentication Mechanism, Message Digest 5) method in addition to the AUTH PLAIN and AUTH LOGIN methods, then the SMTP username is sent in plain text in the SSL tunnel to identify the user, but the SMTP password is transmitted in encrypted form:

• The SMTP client connects to the SMTP server. The SSL connection is confirmed in → line 3 with the status code 220 and a status message.
• The client greets with EHLO and the local host name → line 4.
• The server responds with an overview of possible commands for further transactions in → lines 5 to 11.
• In the example, the client decides to identify and authenticate via CRAM-MD5 and sends the command AUTH CRAM-MD5 to the SMTP server → line 12.
• The SMTP server responds in → line 13 after the status code 334 with a base64-encoded character string - the so-called challenge - consisting of numbers, timestamp and fully qualified host name of the server.
• The SMTP client responds with a string (response) consisting of user name, space and a 'digest'. This digest is the base64-encoded MD5 hash of a value - calculated from the challenge and the password → line 14.
• The SMTP server checks the digest received by performing the same calculation as the SMTP client with user name and user password stored on the server and compares its result with the one received from the client. If both values match, the identified user is also authenticated. This is confirmed in → line 15 after the status code 235.

Console:

[1] hans@linux:~$ openssl s_client -quiet -connect mx.freenet.de:465
[2] ...
[3] 220 mx8.freenet.de ESMTP Exim 4.85 Tue, 02 Feb 2016 07:53:59 +0100
[4] EHLO linux
[5] 250-mx8.freenet.de Hello p4fca44f0.dip0.t-ipconnect.de [79.202.68.240]
[6] 250-SIZE 209715200
[7] 250-8BITMIME
[8] 250-ETRN
[9] 250-PIPELINING
[10] 250-AUTH LOGIN PLAIN CRAM-MD5
[11] 250 HELP
[12] AUTH CRAM-MD5
[13] 334 PDE4OTYuNjk3MTcwOTUyQHBvc3RvZmZpY2UucmVzdG9uLm1jaS5uZXQ+
[14] dGltIGI5MTNhNjAyYzdlZGE3YTQ5NWI0ZTZlNzMzNGQzODkw
[15] 235 Authentication succeeded
[16] QUIT
[17] 221 mx8.freenet.de closing connection
[18] hans@linux:~$

You can use the following function to calculate the response to be sent in line 14. The SMTP user name, the corresponding SMTP user password and the 'task' set by the server are passed as parameters:

[1] Public Function CRAMMD5(sUsername As String, sPassword As String, sChallenge64 As String) As String
[2]
[3]   Dim sChallenge, sCommand, sDigestHex, sResponse As String
[4]
[5]   sChallenge = UnBase64(sChallenge64)
[6]
[7]   sCommand = "openssl md5 -hmac " & Shell$(sPassword) & " << EOF\n" & sChallenge
[8]   Shell sCommand To sDigestHex
[9]
[10]   sDigestHex = Split(Trim(sDigestHex), "=")[1]
[11]   sResponse = Base64(sUsername & sDigestHex)
[12]
[13]   Return sResponse
[14]
[15] End ' Function CRAMMD5(...)

Notes:

• The function value in → line 13 is the response that the server expects.
• Since Gambas version 3.8.4, the CRAM-MD5 method can also be used.
• The SMTP client in Chapter 24.4.1 uses the CRAM-MD5 procedure alternatively and freely selectable.

The following excursus summarises essential, selected aspects on the subject of SMTP:

• SMTP stands for Simple Mail Transfer Protocol.
• The e-mail transport system contains as an element, among others, the service MUA (Mail-User-Agent), which performs the handover of an e-mail to the service MTA (Mail-Transfer-Agent), whereby an MTA is used for forwarding and delivery to a message store. Remote access to the message store is primarily governed by the Post Office Protocol (POP) - currently in version 3.
• SMTP regulates the delivery of an email to a server as an MTA.
• As for all internet protocols, the binding rules for SMTP exist in different descriptions - the RFC.
• SMTP is described in RFC 821 and since 2001 in RFC 2821, where RFC 2821 contains extensions of RFC 821, which has been in force since 1982.
• SMTP is a client-server protocol and requires an active TCP/IP connection between client and server, which the client establishes.
• SMTP is a text-based protocol.
• SMTP initiates transactions between client and server by the client sending commands.
• After each command, the client waits a finite time for the server response (timeout).
• A server response begins with a status code (number of three digits) followed by a (non-normalised) status message.
• SMTP relies on the transport protocol (default). The default port is 25. For an encrypted connection between client and server, SSL switches to port 465 and TLS switches to 587.