smtp_client.h
Go to the documentation of this file.
1 /**
2  * @file smtp_client.h
3  * @brief SMTP client (Simple Mail Transfer Protocol)
4  *
5  * @section License
6  *
7  * Copyright (C) 2010-2018 Oryx Embedded SARL. All rights reserved.
8  *
9  * This file is part of CycloneTCP Open.
10  *
11  * This program is free software; you can redistribute it and/or
12  * modify it under the terms of the GNU General Public License
13  * as published by the Free Software Foundation; either version 2
14  * of the License, or (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program; if not, write to the Free Software Foundation,
23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
24  *
25  * @author Oryx Embedded SARL (www.oryx-embedded.com)
26  * @version 1.9.0
27  **/
28 
29 #ifndef _SMTP_CLIENT_H
30 #define _SMTP_CLIENT_H
31 
32 //Dependencies
33 #include "core/socket.h"
34 
35 //SMTP client support
36 #ifndef SMTP_CLIENT_SUPPORT
37  #define SMTP_CLIENT_SUPPORT ENABLED
38 #elif (SMTP_CLIENT_SUPPORT != ENABLED && SMTP_CLIENT_SUPPORT != DISABLED)
39  #error SMTP_CLIENT_SUPPORT parameter is not valid
40 #endif
41 
42 //Default timeout
43 #ifndef SMTP_CLIENT_DEFAULT_TIMEOUT
44  #define SMTP_CLIENT_DEFAULT_TIMEOUT 10000
45 #elif (SMTP_CLIENT_DEFAULT_TIMEOUT < 1000)
46  #error SMTP_CLIENT_DEFAULT_TIMEOUT parameter is not valid
47 #endif
48 
49 //Maximum line length
50 #ifndef SMTP_CLIENT_MAX_LINE_LENGTH
51  #define SMTP_CLIENT_MAX_LINE_LENGTH 512
52 #elif (SMTP_CLIENT_MAX_LINE_LENGTH < 64)
53  #error SMTP_CLIENT_MAX_LINE_LENGTH parameter is not valid
54 #endif
55 
56 //SMTP over TLS
57 #ifndef SMTP_CLIENT_TLS_SUPPORT
58  #define SMTP_CLIENT_TLS_SUPPORT DISABLED
59 #elif (SMTP_CLIENT_TLS_SUPPORT != ENABLED && SMTP_CLIENT_TLS_SUPPORT != DISABLED)
60  #error SMTP_CLIENT_TLS_SUPPORT parameter is not valid
61 #endif
62 
63 //LOGIN authentication support
64 #ifndef SMTP_CLIENT_LOGIN_AUTH_SUPPORT
65  #define SMTP_CLIENT_LOGIN_AUTH_SUPPORT ENABLED
66 #elif (SMTP_CLIENT_LOGIN_AUTH_SUPPORT != ENABLED && SMTP_CLIENT_LOGIN_AUTH_SUPPORT != DISABLED)
67  #error SMTP_CLIENT_LOGIN_AUTH_SUPPORT parameter is not valid
68 #endif
69 
70 //PLAIN authentication support
71 #ifndef SMTP_CLIENT_PLAIN_AUTH_SUPPORT
72  #define SMTP_CLIENT_PLAIN_AUTH_SUPPORT ENABLED
73 #elif (SMTP_CLIENT_PLAIN_AUTH_SUPPORT != ENABLED && SMTP_CLIENT_PLAIN_AUTH_SUPPORT != DISABLED)
74  #error SMTP_CLIENT_PLAIN_AUTH_SUPPORT parameter is not valid
75 #endif
76 
77 //CRAM-MD5 authentication support
78 #ifndef SMTP_CLIENT_CRAM_MD5_AUTH_SUPPORT
79  #define SMTP_CLIENT_CRAM_MD5_AUTH_SUPPORT DISABLED
80 #elif (SMTP_CLIENT_CRAM_MD5_AUTH_SUPPORT != ENABLED && SMTP_CLIENT_CRAM_MD5_AUTH_SUPPORT != DISABLED)
81  #error SMTP_CLIENT_CRAM_MD5_AUTH_SUPPORT parameter is not valid
82 #endif
83 
84 //SMTP over TLS supported?
85 #if (SMTP_CLIENT_TLS_SUPPORT == ENABLED)
86  #include "core/crypto.h"
87  #include "tls.h"
88 #endif
89 
90 //LOGIN or PLAIN authentication supported?
91 #if (SMTP_CLIENT_LOGIN_AUTH_SUPPORT == ENABLED || SMTP_CLIENT_PLAIN_AUTH_SUPPORT == ENABLED)
92  #include "core/crypto.h"
93  #include "encoding/base64.h"
94 #endif
95 
96 //CRAM-MD5 authentication supported?
97 #if (SMTP_CLIENT_CRAM_MD5_AUTH_SUPPORT == ENABLED)
98  #include "core/crypto.h"
99  #include "encoding/base64.h"
100  #include "mac/hmac.h"
101  #include "hash/md5.h"
102 #endif
103 
104 //SMTP port number
105 #define SMTP_PORT 25
106 //SMTPS port number (SMTP over TLS)
107 #define SMTPS_PORT 465
108 //SMTP message submission port number
109 #define SMTP_SUBMISSION_PORT 587
110 
111 //Test macros for SMTP response codes
112 #define SMTP_REPLY_CODE_2YZ(code) ((code) >= 200 && (code) < 300)
113 #define SMTP_REPLY_CODE_3YZ(code) ((code) >= 300 && (code) < 400)
114 #define SMTP_REPLY_CODE_4YZ(code) ((code) >= 400 && (code) < 500)
115 #define SMTP_REPLY_CODE_5YZ(code) ((code) >= 500 && (code) < 600)
116 
117 //C++ guard
118 #ifdef __cplusplus
119  extern "C" {
120 #endif
121 
122 
123 /**
124  * @brief Recipient type
125  **/
126 
127 typedef enum
128 {
133 
134 
135 /**
136  * @brief Authentication information
137  **/
138 
139 typedef struct
140 {
143  uint16_t serverPort;
144  const char_t *userName;
145  const char_t *password;
146 #if (SMTP_CLIENT_TLS_SUPPORT == ENABLED)
149  void *prngContext;
150 #endif
151 } SmtpAuthInfo;
152 
153 
154 /**
155  * @brief Mail address
156  **/
157 
158 typedef struct
159 {
163 } SmtpMailAddr;
164 
165 
166 /**
167  * @brief Mail contents
168  **/
169 
170 typedef struct
171 {
176  const char_t *subject;
177  const char_t *body;
178 } SmtpMail;
179 
180 
181 /**
182  * @brief SMTP client context
183  **/
184 
185 typedef struct
186 {
187  Socket *socket; ///<Underlying socket
188  bool_t authLoginSupported; ///<LOGIN authentication mechanism supported
189  bool_t authPlainSupported; ///<PLAIN authentication mechanism supported
190  bool_t authCramMd5Supported; ///<CRAM-MD5 authentication mechanism supported
191  bool_t startTlsSupported; ///<STARTTLS command supported
192  char_t buffer[SMTP_CLIENT_MAX_LINE_LENGTH / 2]; ///<Memory buffer for input/output operations
194 #if (SMTP_CLIENT_TLS_SUPPORT == ENABLED)
195  TlsContext *tlsContext; ///<TLS context
196 #endif
198 
199 
200 //Callback function to parse a response line
201 typedef error_t (*SmtpReplyCallback)(SmtpClientContext *context, char_t *replyLine, uint_t replyCode);
202 
203 //SMTP related functions
204 error_t smtpSendMail(const SmtpAuthInfo *authInfo, const SmtpMail *mail);
205 
207  char_t *replyLine, uint_t replyCode);
208 
212 
213 error_t smtpSendData(SmtpClientContext *context, const SmtpMail *mail);
214 
215 error_t smtpSendCommand(SmtpClientContext *context, const char_t *command,
216  uint_t *replyCode, SmtpReplyCallback callback);
217 
218 error_t smtpWrite(SmtpClientContext *context, const void *data, size_t length, uint_t flags);
219 error_t smtpRead(SmtpClientContext *context, void *data, size_t size, size_t *received, uint_t flags);
220 
221 //C++ guard
222 #ifdef __cplusplus
223  }
224 #endif
225 
226 #endif
TLS (Transport Layer Security)
const char_t * subject
Definition: smtp_client.h:176
error_t smtpRead(SmtpClientContext *context, void *data, size_t size, size_t *received, uint_t flags)
Receive data from the SMTP server.
Definition: smtp_client.c:943
error_t(* SmtpReplyCallback)(SmtpClientContext *context, char_t *replyLine, uint_t replyCode)
Definition: smtp_client.h:201
Socket * socket
Underlying socket.
Definition: smtp_client.h:187
bool_t useTls
Definition: smtp_client.h:147
error_t smtpSendAuthLogin(SmtpClientContext *context, const SmtpAuthInfo *authInfo)
Authentication using LOGIN mechanism.
Definition: smtp_client.c:493
char char_t
Definition: compiler_port.h:41
uint8_t flags
Definition: tcp.h:312
SMTP client context.
Definition: smtp_client.h:185
error_t smtpWrite(SmtpClientContext *context, const void *data, size_t length, uint_t flags)
Send data to the SMTP server.
Definition: smtp_client.c:915
Authentication information.
Definition: smtp_client.h:139
bool_t authLoginSupported
LOGIN authentication mechanism supported.
Definition: smtp_client.h:188
char_t * name
Definition: smtp_client.h:160
General definitions for cryptographic algorithms.
#define SMTP_CLIENT_MAX_LINE_LENGTH
Definition: smtp_client.h:51
const char_t * serverName
Definition: smtp_client.h:142
bool_t startTlsSupported
STARTTLS command supported.
Definition: smtp_client.h:191
char_t * dateTime
Definition: smtp_client.h:175
#define Socket
Definition: socket.h:34
uint8_t authInfo[]
HMAC (Keyed-Hashing for Message Authentication)
const char_t * password
Definition: smtp_client.h:145
char_t * addr
Definition: smtp_client.h:161
const char_t * body
Definition: smtp_client.h:177
SmtpMailAddr from
Definition: smtp_client.h:172
void * prngContext
Definition: smtp_client.h:149
error_t smtpSendAuthPlain(SmtpClientContext *context, const SmtpAuthInfo *authInfo)
Authentication using PLAIN mechanism.
Definition: smtp_client.c:555
TlsContext * tlsContext
TLS context.
Definition: smtp_client.h:195
const SmtpMailAddr * recipients
Definition: smtp_client.h:173
bool_t authCramMd5Supported
CRAM-MD5 authentication mechanism supported.
Definition: smtp_client.h:190
error_t smtpSendAuthCramMd5(SmtpClientContext *context, const SmtpAuthInfo *authInfo)
Authentication using CRAM-MD5 mechanism.
Definition: smtp_client.c:603
Mail address.
Definition: smtp_client.h:158
NetInterface * interface
Definition: smtp_client.h:141
error_t smtpEhloReplyCallback(SmtpClientContext *context, char_t *replyLine, uint_t replyCode)
Callback function to parse EHLO response.
Definition: smtp_client.c:430
const char_t * userName
Definition: smtp_client.h:144
error_t
Error codes.
Definition: error.h:40
Base64 encoding scheme.
error_t smtpSendCommand(SmtpClientContext *context, const char_t *command, uint_t *replyCode, SmtpReplyCallback callback)
Send SMTP command and wait for a reply.
Definition: smtp_client.c:835
error_t smtpSendData(SmtpClientContext *context, const SmtpMail *mail)
Send message body.
Definition: smtp_client.c:696
bool_t authPlainSupported
PLAIN authentication mechanism supported.
Definition: smtp_client.h:189
unsigned int uint_t
Definition: compiler_port.h:43
uint8_t data[]
Definition: dtls_misc.h:167
#define NetInterface
Definition: net.h:34
Common interface for pseudo-random number generators.
Definition: crypto.h:1091
error_t smtpSendMail(const SmtpAuthInfo *authInfo, const SmtpMail *mail)
Send a mail to the specified recipients.
Definition: smtp_client.c:61
const PrngAlgo * prngAlgo
Definition: smtp_client.h:148
uint16_t serverPort
Definition: smtp_client.h:143
uint_t recipientCount
Definition: smtp_client.h:174
SmtpRecipientType
Recipient type.
Definition: smtp_client.h:127
Socket API.
uint8_t length
Definition: dtls_misc.h:140
MD5 (Message-Digest Algorithm)
#define TlsContext
Definition: tls.h:34
int bool_t
Definition: compiler_port.h:47
Mail contents.
Definition: smtp_client.h:170