"Fossies" - the Fresh Open Source Software Archive

Member "msmtp-1.8.5/src/smtp.h" (12 Jul 2019, 14420 Bytes) of package /linux/privat/msmtp-1.8.5.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "smtp.h" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 1.8.4_vs_1.8.5.

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