"Fossies" - the Fresh Open Source Software Archive

Member "msmtp-1.8.17/src/smtp.h" (26 Dec 2020, 14518 Bytes) of package /linux/privat/msmtp-1.8.17.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 last Fossies "Diffs" side-by-side code changes report: 1.8.14_vs_1.8.15.

    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