1 /* 2 * smtp.h 3 * 4 * This file is part of msmtp, an SMTP client. 5 * 6 * Copyright (C) 2000, 2003, 2004, 2005, 2006, 2008, 2010, 2012, 2014, 2016, 7 * 2018, 2019, 2020 8 * Martin Lambers <marlam@marlam.de> 9 * 10 * This program is free software; you can redistribute it and/or modify 11 * it under the terms of the GNU General Public License as published by 12 * the Free Software Foundation; either version 3 of the License, or 13 * (at your option) any later version. 14 * 15 * This program is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU General Public License for more details. 19 * 20 * You should have received a copy of the GNU General Public License 21 * along with this program. If not, see <http://www.gnu.org/licenses/>. 22 */ 23 24 #ifndef SMTP_H 25 #define SMTP_H 26 27 #include <stdio.h> 28 29 #include "list.h" 30 #include "readbuf.h" 31 #ifdef HAVE_TLS 32 # include "mtls.h" 33 #endif /* HAVE_TLS */ 34 35 36 /* SMTP errors */ 37 38 /* 39 * If a function with an 'errstr' argument returns a value != SMTP_EOK, 40 * '*errstr' either points to an allocates string containing an error 41 * description or is NULL. 42 * If such a function returns SMTP_EOK, 'errstr' will not be changed. 43 */ 44 #define SMTP_EOK 0 /* no error */ 45 #define SMTP_EIO 1 /* Input/output error */ 46 #define SMTP_EPROTO 2 /* Protocol violation */ 47 #define SMTP_EINVAL 3 /* Invalid input data */ 48 #define SMTP_EUNAVAIL 4 /* Requested service unavailable */ 49 #define SMTP_EAUTHFAIL 5 /* Authentication failed */ 50 #define SMTP_ELIBFAILED 6 /* An underlying library failed */ 51 #define SMTP_EINSECURE 7 /* The requested action would be 52 insecure */ 53 54 /* SMTP sub protocols */ 55 #define SMTP_PROTO_SMTP 0 /* default: SMTP / ESMTP */ 56 #define SMTP_PROTO_LMTP 1 /* LMTP, RFC 2033 */ 57 58 59 /* SMTP capabilities */ 60 61 #define SMTP_CAP_STARTTLS (1 << 0) 62 #define SMTP_CAP_DSN (1 << 1) 63 #define SMTP_CAP_PIPELINING (1 << 2) 64 #define SMTP_CAP_SIZE (1 << 3) 65 #define SMTP_CAP_AUTH (1 << 4) 66 #define SMTP_CAP_AUTH_PLAIN (1 << 5) 67 #define SMTP_CAP_AUTH_LOGIN (1 << 6) 68 #define SMTP_CAP_AUTH_CRAM_MD5 (1 << 7) 69 #define SMTP_CAP_AUTH_DIGEST_MD5 (1 << 8) 70 #define SMTP_CAP_AUTH_SCRAM_SHA_1 (1 << 9) 71 #define SMTP_CAP_AUTH_GSSAPI (1 << 10) 72 #define SMTP_CAP_AUTH_EXTERNAL (1 << 11) 73 #define SMTP_CAP_AUTH_NTLM (1 << 12) 74 #define SMTP_CAP_AUTH_OAUTHBEARER (1 << 13) 75 #define SMTP_CAP_AUTH_XOAUTH2 (1 << 14) 76 #define SMTP_CAP_ETRN (1 << 15) 77 #define SMTP_CAP_AUTH_SCRAM_SHA_256 (1 << 16) 78 79 80 /* 81 * This structure describes the capabilities of an SMTP server. 82 * 'flags' is a combination of the SMTP_CAP_* values above. 83 * If (flags & SMTP_CAP_SIZE), 'size' contains the max size of a message that 84 * the SMTP server will accept (0 means there is no limit). 85 */ 86 typedef struct 87 { 88 int flags; 89 long size; 90 } smtp_cap_t; 91 92 /* 93 * This structure represents an SMTP server. Do not access it directly. 94 */ 95 typedef struct 96 { 97 int fd; 98 #ifdef HAVE_TLS 99 mtls_t mtls; 100 #endif /* HAVE_TLS */ 101 readbuf_t readbuf; 102 int protocol; 103 smtp_cap_t cap; 104 FILE *debug; 105 } smtp_server_t; 106 107 108 /* 109 * smtp_new() 110 * 111 * Create a new smtp_server_t. If 'debug' is not NULL, the complete 112 * conversation with the SMTP server will be logged to the referenced file. 113 * Beware: this log may contain user passwords. 114 * 'protocol' must be one of the SMTP_PROTO_* constants. 115 */ 116 smtp_server_t smtp_new(FILE *debug, int protocol); 117 118 /* 119 * smtp_connect() 120 * 121 * Connect to a SMTP server. See net_open_socket(). 122 * If 'server_canonical_name' is not NULL, a pointer to a string containing the 123 * canonical hostname of the server will be stored in '*server_canonical_name', 124 * or NULL if this information is not available. 125 * If 'server_address' is not NULL, a pointer to a string containing the 126 * network address of the server will be stored in '*server_address', 127 * or NULL if this information is not available. 128 * Both strings are allocated. 129 * Used error codes: NET_EHOSTNOTFOUND, NET_ESOCKET, NET_ECONNECT, NET_EPROXY 130 * Success: NET_EOK 131 */ 132 int smtp_connect(smtp_server_t *srv, 133 const char *socketname, 134 const char *proxy_host, int proxy_port, 135 const char *host, int port, const char *source_ip, int timeout, 136 char **server_canonical_name, char **server_address, 137 char **errstr); 138 139 /* 140 * smtp_msg_status() 141 * 142 * Returns the three digit status code of the SMTP server message 'msg', which 143 * *must* be a valid SMTP server message. 144 */ 145 int smtp_msg_status(list_t *msg); 146 147 /* 148 * smtp_get_greeting() 149 * 150 * Get the greeting message from the SMTP server. 151 * If 'buf' is not NULL, it will contain a pointer to an allocated string 152 * containing the identificatin string of the SMTP server (untrusted data!) 153 * Used error codes: SMTP_EIO, SMTP_EPROTO 154 */ 155 int smtp_get_greeting(smtp_server_t *srv, list_t **errmsg, char **buf, 156 char **errstr); 157 158 /* 159 * smtp_init() 160 * 161 * Initialize an SMTP session with the connected SMTP server 'srv' 162 * (via the SMTP EHLO/HELO command). This function must be used after 163 * the server is connected and before any mail is send. It must also be used 164 * (a second time) after TLS is started via the STARTTLS command. 165 * This function determines the capabilities of the SMTP server. 166 * 'ehlo_domain' is the parameter for the EHLO/HELO command. If you don't know 167 * what to use, use "localhost". 168 * 'error_msg' contains an error message from the SMTP server or NULL. 169 * Used error codes: SMTP_EIO, SMTP_EPROTO, SMTP_EINVAL 170 */ 171 int smtp_init(smtp_server_t *srv, const char *ehlo_domain, list_t **msg, 172 char **errstr); 173 174 /* 175 * smtp_tls_init() 176 * 177 * Prepare TLS encryption. See tls_init() for a description of the arguments. 178 * Used error codes: TLS_ELIBFAILED, TLS_EFILE 179 * Success: TLS_EOK 180 */ 181 #ifdef HAVE_TLS 182 int smtp_tls_init(smtp_server_t *srv, 183 const char *tls_key_file, const char *tls_cert_file, const char *pin, 184 const char *tls_trust_file, const char *tls_crl_file, 185 const unsigned char *tls_sha256_fingerprint, 186 const unsigned char *tls_sha1_fingerprint, 187 const unsigned char *tls_md5_fingerprint, 188 int min_dh_prime_bits, 189 const char *priorities, 190 const char *hostname, 191 int no_certcheck, 192 char **errstr); 193 #endif /* HAVE_TLS */ 194 195 /* 196 * smtp_tls_starttls() 197 * 198 * Announce the start of TLS encryption with an initialized SMTP server, 199 * using the STARTTLS command. 200 * Use this function after smtp_init(). The SMTP server must have the 201 * SMTP_CAP_STARTTLS capability. 202 * Call smtp_tls() afterwards. Finally, call smtp_init() again (the SMTP server 203 * might advertise different capabilities when TLS is active, for example 204 * cleartext authentication mechanisms). 205 * 'error_msg' contains the error message from the SMTP server or NULL. 206 * Used error codes: SMTP_EIO, SMTP_EPROTO, SMTP_EINVAL 207 */ 208 #ifdef HAVE_TLS 209 int smtp_tls_starttls(smtp_server_t *srv, list_t **error_msg, char **errstr); 210 #endif /* HAVE_TLS */ 211 212 /* 213 * smtp_tls() 214 * 215 * Start TLS with a connected SMTP server. 216 * Use this function either after smtp_connect() for SMTP servers 217 * that use TLS without the STARTTLS command (service smtps; default port 465), 218 * or after smtp_tls_starttls() for SMTP servers that support the STARTTLS 219 * command. 220 * See tls_start() for a description of the arguments. 221 * Used error codes: TLS_ELIBFAILED, TLS_ECERT, TLS_EHANDSHAKE 222 * Success: TLS_EOK 223 */ 224 #ifdef HAVE_TLS 225 int smtp_tls(smtp_server_t *srv, 226 mtls_cert_info_t *tci, char **tls_parameter_description, char **errstr); 227 #endif /* HAVE_TLS */ 228 229 /* 230 * smtp_client_supports_authmech() 231 * 232 * Returns 1 if the authentication mechanism is supported by the underlying 233 * authentication code and 0 otherwise. 234 */ 235 int smtp_client_supports_authmech(const char *mech); 236 237 /* 238 * smtp_server_supports_authmech() 239 * 240 * Returns 1 if the authentication mechanism is supported by the SMTP server 241 * and 0 otherwise. 242 */ 243 int smtp_server_supports_authmech(smtp_server_t *srv, const char *mech); 244 245 /* 246 * smtp_auth() 247 * 248 * Authentication. 249 * Use smtp_client_supports_authmech() and smtp_server_supports_authmech() 250 * to find out which authentication mechanisms are available. 251 * The special value "" for 'auth_mech' causes the function to choose the best 252 * authentication method supported by the server, unless TLS is incative and the 253 * method sends cleartext passwords. In this case, the function fails with 254 * SMTP_EINSECURE. 255 * The hostname is the name of the SMTP server. It may be needed for 256 * authentication. 257 * The port is port number SMTP server accepts connections on. It may be needed 258 * for authentication. 259 * The ntlmdomain may be NULL (even if you use NTLM authentication). 260 * If 'password' is NULL, but the authentication method needs a password, 261 * the 'password_callback' function is called (if 'password_callback' is not 262 * NULL). It is expected to return a * password in an allocated buffer or NULL 263 * (if it fails). 264 * 'error_msg' contains the error message from the SMTP server or NULL. 265 * Used error codes: SMTP_EIO, SMTP_EINVAL, SMTP_EPROTO, SMTP_EAUTHFAIL, 266 * SMTP_ELIBFAILED, SMTP_EINSECURE, SMTP_EUNAVAIL 267 */ 268 int smtp_auth(smtp_server_t *srv, 269 const char *hostname, 270 unsigned short port, 271 const char *user, 272 const char *password, 273 const char *ntlmdomain, 274 const char *auth_mech, 275 char *(*password_callback)(const char *hostname, const char *user), 276 list_t **error_msg, 277 char **errstr); 278 279 /* 280 * smtp_envelope() 281 * 282 * Sends the mail envelope (sender, recipients, ...) 283 * The mail data must be sent immediately afterwards with smtp_send_mail() 284 * envelope_from: The envelope from address 285 * recipients: The list of recipients 286 * dsn_notify: Delivery Status Notification request string (see man 287 * page) or NULL. The SMTP server must support 288 * SMTP_CAP_DSN. 289 * dsn_return: Either "HDRS", "FULL" or NULL. The SMTP server must 290 * support SMTP_CAP_DSN. 291 * error_msg: If an error occurs, this will contain the SMTP server 292 * message (or NULL) 293 * Used error codes: SMTP_EIO, SMTP_EPROTO, SMTP_EINVAL, SMTP_EUNAVAIL 294 */ 295 int smtp_send_envelope(smtp_server_t *srv, 296 const char *envelope_from, 297 list_t *recipients, 298 const char *dsn_notify, 299 const char *dsn_return, 300 list_t **error_msg, 301 char **errstr); 302 303 /* 304 * smtp_send_mail() 305 * 306 * Sends a mail via the SMTP server 'srv'. 307 * You can use this function more than once to send the mail in chunks. 308 * When you're done, call smtp_end_mail(). 309 * keep_from, keep_to, keep_cc, keep_bcc: 310 * These flags signal if the corresponding header should be kept or removed. 311 * You typically want to set keep_from, keep_to, keep_cc, but not keep_bcc. 312 * You should set all flags when sending mail data without preceding headers, 313 * to avoid accidental removal of mail body contents. 314 * mailf: The file containing the mail 315 * mailsize: This counter will be increased by the number of bytes 316 * of the mail (as transferred to the SMTP server) in case 317 * of successful delivery; the contents are undefined in 318 * case of failure). 319 * error_msg: If an error occurs, this will contain the SMTP server 320 * message (or NULL) 321 * Used error codes: SMTP_EIO 322 */ 323 int smtp_send_mail(smtp_server_t *srv, FILE *mailf, 324 int keep_from, int keep_to, int keep_cc, int keep_bcc, 325 long *mailsize, char **errstr); 326 327 /* 328 * smtp_end_mail() 329 * 330 * Sends a single dot on a line to the SMTP server, signalling that the 331 * transmission of mail data is complete. 332 * This function only works for the SMTP protocol; for LMTP, use 333 * smtp_end_mail_lmtp() instead. 334 * Unlike other functions, this function always returns the SMTP server's 335 * message, unless the return code is SMTP_EIO. 336 * Used error codes: SMTP_EIO, SMTP_EUNAVAIL 337 */ 338 int smtp_end_mail(smtp_server_t *srv, list_t **msg, char **errstr); 339 340 /* 341 * smtp_end_mail_lmtp() 342 * 343 * This function only works for the LMTP protocol; for SMTP, use 344 * smtp_end_mail() instead. 345 * 346 * It sends a single dot on a line to the SMTP server, signalling that the 347 * transmission of mail data is complete. 348 * 349 * The server sends one reply per recipient (therefore 'recipients' must be 350 * the same list that was given to smtp_send_envelope()). 351 * 352 * If all of these replies are positive, SMTP_EOK will be returned. 353 * If an IO error occurred, SMTP_EIO will be returned (as always). 354 * In both cases, 'errstrs' and 'error_msgs' will be NULL. 355 * 356 * If one or more of the replies are negative, SMTP_EUNAVAIL will be returned, 357 * and 'errstrs' and 'error_msgs' will contain one entry for each entry in the 358 * 'recipients' list. If the corresponding recipient caused a positive reply, 359 * both the 'errstrs' and 'error_msgs' entries will be NULL; if it caused a 360 * negative reply, the 'errstrs' entry will contain an error message and the 361 * 'error_msgs' entry will contain the negative reply. 362 * 363 * Used error codes: SMTP_EIO, SMTP_EUNAVAIL 364 */ 365 int smtp_end_mail_lmtp(smtp_server_t *srv, 366 list_t *recipients, 367 list_t **errstrs, 368 list_t **error_msgs, 369 char **errstr); 370 371 /* 372 * smtp_etrn() 373 * 374 * Send a Remote Message Queue Starting request to the SMTP server via the ETRN 375 * command (RFC 1985). 376 * Used error codes: SMTP_EIO, SMTP_EINVAL, SMTP_EUNAVAIL, SMTP_EPROTO 377 */ 378 int smtp_etrn(smtp_server_t *srv, const char *etrn_argument, 379 list_t **msg, char **errstr); 380 381 /* 382 * smtp_quit() 383 * 384 * Sends the QUIT command to the SMTP server 'srv' to end the current session. 385 * Use smtp_close() after this function. 386 * Used error codes: SMTP_EIO, SMTP_EPROTO, SMTP_EINVAL 387 */ 388 int smtp_quit(smtp_server_t *srv, char **errstr); 389 390 /* 391 * smtp_close() 392 * 393 * Closes the connection to the SMTP server 'srv'. 394 * 'srv' is unusable afterwards; reinitialize it with smtp_new() if you want 395 * to reuse it. 396 */ 397 void smtp_close(smtp_server_t *srv); 398 399 /* 400 * smtp_exitcode() 401 * 402 * Translate SMTP_* error code to an error code from sysexits.h 403 */ 404 int smtp_exitcode(int smtp_error_code); 405 406 #endif 407