Transmitting e-mails with the library "WagoLibMail_02.lib", English Version 1.1.0
2 General Copyright 2006 by WAGO Kontakttechnik GmbH & Co. KG All rights reserved. WAGO Kontakttechnik GmbH & Co. KG Hansastraße 27 D-32423 Minden Phone: +49 (0) 571/8 87 0 Fax: +49 (0) 571/8 87 1 69 E-Mail: info@wago.com Web: http://www.wago.com Technical Support Phone: +49 (0) 571/8 87 5 55 Fax: +49 (0) 571/8 87 85 55 E-Mail: support@wago.com Every conceivable measure has been taken to ensure the correctness and completeness of this documentation. However, as errors can never be fully excluded we would appreciate any information or ideas at any time. We wish to point out that the software and hardware terms as well as the trademarks of companies used and/or mentioned in the present manual are generally trademark or patent protected.
Table of Contents 3 TABLE OF CONTENTS 1 Important comments...4 1.1 Legal principles...4 1.1.1 Copyright...4 1.1.2 Personnel qualification...4 1.1.3 Intended use...4 1.2 Range of validity...5 1.3 Symbols...5 2 Description...6 2.1 Transmitting mails...7 3 Sending mails via SMTP...8 3.1 Used material...9 4 Sending mails using POP3 before SMTP...10 4.1 Used material...10 5 Sending mails using SMTP Authentication...11 5.1 Used material...11 6 Sending different mails with one instance...12 6.1 Used material...12
4 Important comments 1 Important comments 1.1 Legal principles 1.1.1 Copyright To ensure fast installation and start-up of the units described in this manual, we strongly recommend that the following information and explanation is carefully read and adhered to. This manual is copyrighted, together with all figures and illustrations contained therein. Any use of this manual which infringes the copyright provisions stipulated herein, is not permitted. Reproduction, translation and electronic and photo-technical archiving and amendments require the written consent of WAGO Kontakttechnik GmbH & Co. KG. Non-observance will entail the right of claims for damages. 1.1.2 Personnel qualification 1.1.3 Intended use The use of the product detailed in this manual is exclusively geared to specialists having qualifications in PLC programming, electrical specialists or persons instructed by electrical specialists who are also familiar with the valid standards. WAGO Kontakttechnik GmbH & Co. KG declines all liability resulting from improper action and damage to WAGO products and third party products due to non-observance of the information contained in this manual. For each individual application, the components supplied are to work with a dedicated hardware and software configuration. Modifications are only admitted within the framework of the possibilities documented in the manuals. All other changes to the hardware and/or software and the non-conforming use of the components entail the exclusion of liability on part of WAGO Kontakttechnik GmbH & Co. KG. Please direct any requirements pertaining to a modified and/or new hardware or software configuration directly to WAGO Kontakttechnik GmbH & Co. KG.
Important comments 5 1.2 Range of validity 1.3 Symbols This application note is based on the stated hardware and software of the specific manufacturer as well as the correspondent documentation. This application note is therefore only valid for the described installation. New hardware and software versions may need to be handled differently. Please note the detailed description in the specific manuals. Danger Always observe this information to protect persons from injury. Warning Always observe this information to prevent damage to the device. Attention Marginal conditions must always be observed to ensure smooth operation. ESD (Electrostatic Discharge) Warning of damage to the components by electrostatic discharge. Observe the precautionary measure for handling components at risk. Note Routines or advice for efficient use of the device and software optimisation. More information References to additional literature, manuals, data sheets and INTERNET pages
6 Description 2 Description The library WagoLibMail_02.lib provide with MAIL_ESMTP_Client a one for all function block for sending mails by an Ethernet-Controller 750-841 as well as an 758-870. The function block MAIL_ESMTP_Client could work as a simple SMTP- Client as well as the function block supports the authentication methods Pop3BeforeSmtp and SMTP-Authentication who described in RFC2554. Supported authentication types are CRAM-MD5, LOGIN and PLAIN. This application note shows chapter for chapter the different usage of the function block MAIL_ESMTP_Client on a WAGO ethernet controller 750-841 and give some technological backround information about dispatching mails. The starting point of this document should be a server, with a valid mail account, who proper respond the the ICMP-Ping service as shown below. This application note do not address router configuration or what ever needed to make a server accessible.
Description 7 2.1 Transmitting mails SMTP means Simple Mail Transfer Protocol and is one of the first internet protocols. SMTP do not use a direct connection with the mails recipient to deliver mails. There are two steps needed before a mail can be read by the recipient. SMTP is a "push" protocol that does not allow one to "pull" messages from a remote server, this task will be done by the POP3 protocol. In the first step the mail is transfered(push) to your providers SMTP server, who (can) relay the mail to an other provider. The recipients provider will store the mail until the recipient will ask(pull) for incomming mails by POP or IMAP. SMTP was designed in a time where each network participant principially rated as honest. For this reason SMTP (RFC821) covers no authentication features. Some Providers close the gap with Pop3BeforeSmtp other implement the SMTP service extension for authentication (RFC2554) known as SMTP- AUTH.
8 Sending mails via SMTP 3 Sending mails via SMTP The examples WagoLibMail02_Example01 and WagoLibMail02- Example02 point out how to send mails in a local network, with and whitout attachment. This examples use the mail server from ArGoSoft what is aviable as freeware on the internet. To run the examples download the ArGoSoft Mail Server, configure the domainname and create one or more user accounts. Attention - this version do not relay mails, so the receiver must be a member of the same domain, otherwise you get the errormessage 550 we dont relay. Until now the mails for moeller@application.local will be stored on the server. To see this mails in Outlook2000 you can add an entry with: START->Extras->Services->Add. Above you see the correspondend screenshot. To do so, you need the administators privileg.
Sending mails via SMTP 9 The following screenshot shows the whole example program. 3.1 Used material To run the example act as follow: - Download the program into the 750-841 with [Alt] + [F8]. - Start the Program with [F5]. - Dobble-Click on input xmystart to select TRUE. as write value. - Write values into 750-841 with [Strg] + [F7]. The input xsend will be reset bei the function block if: - the transfer finished - an error occurd. - the configured ttimeout elapsed. Check ierror after the falling edge of xsend to detect if transfer was successful. The connection was tested under the following prerequisites. Description Vendorr Type Ethernet-Controller WAGO 750-841 WAGO-I/O Pro CAA CoDeSys 2.3.6.1 Mail Server www.argosoft.com ArGoSoft version 1.8 Mail Server Mircosoft Exchange 2000 Mail Client Mircosoft Outlook 2000
10 Sending mails using POP3 before SMTP 4 Sending mails using POP3 before SMTP The security feature Pop3BeforeSmtp also known as SmtpAfterPop should prevent outside users to use the mail server to relay messages. SMTP does not have any restrictions. POP3 and IMAP mail clients must always authenticate their users before they can access their mail boxes. The basic idear behind is that the SMTP Server only accept TCP connection from IP-adresses who just have taken a look into their mailbox. by POP3 or IMAP. To do so the mail server store the ip-address of every succsessful POP3 authentication for a small period of time.this works for most internet mail clients because most mail clients always check for mail just before sending messages. The example WagoLibMail02_Example03 permits transmitting mails to any recipient in the Internet. The example requires a valid web.de account such as access to the internet. Dont forget to configure the Gateway entry of the ethernet-controller 750-841 and check the accessability with ICMP-Ping. Mail account Provider Server name/ Server address Emailaddress Username Password Security features Pop3 server name/ Pop3 server address Sender web.de smtp.web.de/ 217.72.192.157 my.name@web.de my.name secret Pop3BeforeSmtp pop3.web.de/ 217.72.192.134 4.1 Used material The example use the known IP-addresses to configure the servers If you like to configure the servers by their names smtp.web.de and pop3.web.de The ethernet controller 750-841 additional needs a configured DNS server entry. The DNS-Request work with a fix 5 second timeout. If the name resolution telegram (DNS-Request) is the first packet that initiate a dial out connection in to the internet, the connection have to be established within these 5 seconds - for a proper operation, otherwise the function block fails. This may e.g. happen if an analog telephone line is used since it takes approximately 30sec to establish a connection to the internet. In this case wait until the connection is established and try again. The connection was tested under the following prerequisites. Description Vendorr Type Ethernet-Controller WAGO 750-841 FW=>10 WAGO-I/O Pro CAA CoDeSys 2.3.6.1 Mail Client Mircosoft Outlook 2000 Router to internet 3COM 56k LAN Modem 3C888-ME
Sending mails using SMTP Authentication 11 5 Sending mails using SMTP Authentication The example WagoLibMail02_Example04 permits transmitting mails to any recipient in the internet using SMTP-AUTH. The example requires a valid freenet.de account such as access to the internet. Dont forget to configure the Gateway and DNS entry of the ethernet-controller 750-841 and check the SMTP servers accessability with ICMP-Ping. By setting the variable xsend to True a mail will be transmitted. Mail account Provider Server name/ Server address Emailaddress Username Password Security features Sender freenet.de mx.freenet.de/??? my.name@freenet.de my.name@freenet.de secret SMTP-AUTH 5.1 Used material The SMTP service extension add authentication mechanism to SMTP. The extension perform an authentication protocol exchange who allow only legitimate users to relay mails while denying relay service to unauthorized users, such as spammers. The function block MAIL_ESMTP_Client support the authentication mechanism CRAM-MD5, LOGIN and PLAIN. The mechanism PLAIN and LOGIN transport unencrypted passwords, because the Base64 encoding is no encryption. For this reason PLAIN and LOGIN should not used outside of secure connections(tls/ssl). In practice CRAM-MD5 is the only allowed and supported SASL-mechanism for ESMTPA without Transport Layer Security (TLS). In CRAM-MD5 authentication the server first sends a challenge string to the client. The client responds with a username followed by a space character and then a 16-byte digest in hexadecimal notation. The digest is the output of HMAC-MD5 with the user's password as the secret key, and the server's original challenge as the message. The server also calculates its own digest with its notion of the user's password, and if the client's digest and the server's digest match then authentication was successful. The connection was tested under the following prerequisites. Description Vendorr Type Ethernet-Controller WAGO 750-841 FW=>10 WAGO-I/O Pro CAA CoDeSys 2.3.6.1 Mail Client Mircosoft Outlook 2000 Router to internet 3COM 56k LAN Modem 3C888-ME
12 Sending different mails with one instance 6 Sending different mails with one instance The example WagoLibMail02_Example05 point out one way to send different mails using one instance of the MAIL_ESMTP_Client function block. This examples use the mail server from ArGoSoft what is aviable as freeware on the internet. To run the examples download the ArGoSoft Mail Server, configure the domainname and create one or more user accounts. 6.1 Used material The connection was tested under the following prerequisites. Description Vendorr Type Ethernet-Controller WAGO 750-841 WAGO-I/O Pro CAA CoDeSys 2.3.6.1 Mail Server www.argosoft.com ArGoSoft version 1.8 Mail Server Mircosoft Exchange 2000 Mail Client Mircosoft Outlook 2000
Sending different mails with one instance 13
WAGO Kontakttechnik GmbH & Co. KG Postfach 2880 D-32385 Minden Hansastraße 27 D-32423 Minden Phone: 05 71/8 87 0 Telefax: 05 71/8 87 1 69 E-Mail: info@wago.com Internet: http://www.wago.com