"Fossies" - the Fresh Open Source Software Archive

Member "msmtp-1.8.5/src/tls.h" (25 Jun 2019, 7850 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 "tls.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  * tls.h
    3  *
    4  * This file is part of msmtp, an SMTP client.
    5  *
    6  * Copyright (C) 2000, 2003, 2004, 2005, 2006, 2007, 2008, 2010, 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 TLS_H
   25 #define TLS_H
   26 
   27 #ifdef HAVE_LIBGNUTLS
   28 # include <gnutls/gnutls.h>
   29 #endif /* HAVE_LIBGNUTLS */
   30 #ifdef HAVE_LIBSSL
   31 # include <openssl/ssl.h>
   32 #endif /* HAVE_LIBSSL */
   33 
   34 #include "readbuf.h"
   35 
   36 
   37 /*
   38  * If a function with an 'errstr' argument returns a value != TLS_EOK,
   39  * '*errstr' either points to an allocates string containing an error
   40  * description or is NULL.
   41  * If such a function returns TLS_EOK, 'errstr' will not be changed.
   42  */
   43 #define TLS_EOK         0       /* no error */
   44 #define TLS_ELIBFAILED  1       /* The underlying library failed */
   45 #define TLS_ESEED       2       /* Cannot seed pseudo random number generator */
   46 #define TLS_ECERT       3       /* Certificate check or verification failed */
   47 #define TLS_EIO         4       /* Input/output error */
   48 #define TLS_EFILE       5       /* A file does not exist/cannot be read */
   49 #define TLS_EHANDSHAKE  6       /* TLS handshake failed */
   50 
   51 /*
   52  * Always use tls_clear() before using a tls_t!
   53  * Never call a tls_*() function with tls_t NULL!
   54  */
   55 
   56 typedef struct
   57 {
   58     int is_active;
   59     int have_trust_file;
   60     int have_sha256_fingerprint;
   61     int have_sha1_fingerprint;
   62     int have_md5_fingerprint;
   63     unsigned char fingerprint[32];
   64     int no_certcheck;
   65     char *hostname;
   66 #ifdef HAVE_LIBGNUTLS
   67     gnutls_session_t session;
   68     gnutls_certificate_credentials_t cred;
   69 #endif /* HAVE_LIBGNUTLS */
   70 #ifdef HAVE_LIBSSL
   71     SSL_CTX *ssl_ctx;
   72     SSL *ssl;
   73 #endif /* HAVE_LIBSSL */
   74 } tls_t;
   75 
   76 /*
   77  * Information about a X509 certificate.
   78  * The 6 owner_info and issuer_info fields are:
   79  *   Common Name
   80  *   Organization
   81  *   Organizational unit
   82  *   Locality
   83  *   State/Province
   84  *   Country
   85  * Each of these entries may be NULL if it was not provided.
   86  */
   87 typedef struct
   88 {
   89     unsigned char sha256_fingerprint[32];
   90     unsigned char sha1_fingerprint[20];
   91     time_t activation_time;
   92     time_t expiration_time;
   93     char *owner_info[6];
   94     char *issuer_info[6];
   95 } tls_cert_info_t;
   96 
   97 /*
   98  * tls_lib_init()
   99  *
  100  * Initialize underlying TLS library. If this function returns TLS_ELIBFAILED,
  101  * *errstr will always point to an error string.
  102  * Used error codes: TLS_ELIBFAILED
  103  */
  104 int tls_lib_init(char **errstr);
  105 
  106 /*
  107  * tls_clear()
  108  *
  109  * Clears a tls_t type (marks it inactive).
  110  */
  111 void tls_clear(tls_t *tls);
  112 
  113 /*
  114  * tls_init()
  115  *
  116  * Initializes a tls_t. If both 'key_file' and 'cert_file' are not NULL, they
  117  * are set to be used when the peer request a certificate.
  118  * If 'key_file' and 'cert_file' are PKCS11 URIS, a PIN might be needed to access
  119  * e.g. a smart card; this must be given in 'pin' (which can be NULL if there is no PIN).
  120  * If 'trust_file' is
  121  * not NULL, it will be used to verify the peer certificate. If additionally
  122  * 'crl_file' is not NULL, then this file will be used during verification to
  123  * check if a certificate has been revoked. If 'trust_file' is NULL and one of
  124  * 'sha256_fingerprint' or 'sha1_fingerprint' or 'md5_fingerprint' is not NULL,
  125  * then the fingerprint of the peer certificate will be compared to the given
  126  * fingerprint and the certificate is trusted when they match.
  127  * All files must be in PEM format.
  128  * If 'min_dh_prime_bits' is greater than or equal to zero, then only DH primes
  129  * that have at least the given size will be accepted. For values less than
  130  * zero, the library default is used.
  131  * If 'priorities' is not NULL, it must contain a string describing the TLS
  132  * priorities. This is library dependent; see gnutls_priority_init().
  133  * 'hostname' is the host to start TLS with. It is needed for sanity checks/
  134  * verification.
  135  * If 'no_certcheck' is true, then no checks will be performed on the peer
  136  * certificate. If it is false and no trust file was set with tls_init(),
  137  * only sanity checks are performed on the peer certificate. If it is false
  138  * and a trust file was set, real verification of the peer certificate is
  139  * performed.
  140  * Used error codes: TLS_ELIBFAILED, TLS_EFILE
  141  */
  142 int tls_init(tls_t *tls,
  143         const char *key_file, const char *cert_file, const char* pin,
  144         const char *trust_file, const char *crl_file,
  145         const unsigned char *sha256_fingerprint,
  146         const unsigned char *sha1_fingerprint,
  147         const unsigned char *md5_fingerprint,
  148         int min_dh_prime_bits, const char *priorities,
  149         const char *hostname,
  150         int no_certcheck,
  151         char **errstr);
  152 
  153 /*
  154  * tls_start()
  155  *
  156  * Starts TLS encryption on a socket.
  157  * 'tls' must be initialized using tls_init().
  158  * 'tci' must be allocated with tls_cert_info_new(). Information about the
  159  * peer's certificata will be stored in it. It can later be freed with
  160  * tls_cert_info_free(). 'tci' is allowed to be NULL; no certificate
  161  * information will be passed in this case.
  162  * 'tls_parameter_description' may be NULL; if it is not, it will be used
  163  * to return an allocated string describing the TLS session parameters.
  164  * Used error codes: TLS_ELIBFAILED, TLS_ECERT, TLS_EHANDSHAKE
  165  */
  166 int tls_start(tls_t *tls, int fd,
  167         tls_cert_info_t *tci, char **tls_parameter_description, char **errstr);
  168 
  169 /*
  170  * tls_is_active()
  171  *
  172  * Returns whether 'tls' is an active TLS connection.
  173  */
  174 int tls_is_active(tls_t *tls);
  175 
  176 /*
  177  * tls_cert_info_new()
  178  * Returns a new tls_cert_info_t
  179  */
  180 tls_cert_info_t *tls_cert_info_new(void);
  181 
  182 /*
  183  * tls_cert_info_free()
  184  * Frees a tls_cert_info_t
  185  */
  186 void tls_cert_info_free(tls_cert_info_t *tci);
  187 
  188 /*
  189  * tls_cert_info_get()
  190  *
  191  * Extracts certificate information from the TLS connection 'tls' and stores
  192  * it in 'tci'. See the description of tls_cert_info_t above.
  193  * Used error codes: TLS_ECERT
  194  */
  195 int tls_cert_info_get(tls_t *tls, tls_cert_info_t *tci, char **errstr);
  196 
  197 /*
  198  * tls_print_info()
  199  *
  200  * Prints information about a TLS session.
  201  */
  202 void tls_print_info(const char *tls_parameter_description,
  203         const tls_cert_info_t *tci);
  204 
  205 /*
  206  * tls_gets()
  207  *
  208  * Reads in at most one less than 'size' characters from 'tls' and stores them
  209  * into the buffer pointed 'str'. Reading stops after an EOF or a newline.
  210  * If a newline is read, it is stored into the buffer. A '\0' is stored after
  211  * the last character in the buffer. The length of the resulting string (the
  212  * number of characters excluding the terminating '\0') will be stored in 'len'.
  213  * 'readbuf' will be used as an input buffer and must of course be the same for
  214  * all read operations on 'tls'.
  215  * Used error codes: TLS_EIO
  216  */
  217 int tls_gets(tls_t *tls, readbuf_t *readbuf,
  218         char *str, size_t size, size_t *len, char **errstr);
  219 
  220 /*
  221  * tls_puts()
  222  *
  223  * Writes 'len' characters from the string 's' using TLS.
  224  * Used error codes: TLS_EIO
  225  */
  226 int tls_puts(tls_t *tls, const char *s, size_t len, char **errstr);
  227 
  228 /*
  229  * tls_close()
  230  *
  231  * Close a TLS connection and mark it inactive
  232  */
  233 void tls_close(tls_t *tls);
  234 
  235 /*
  236  * tls_lib_deinit()
  237  *
  238  * Deinit underlying TLS library.
  239  */
  240 void tls_lib_deinit(void);
  241 
  242 /*
  243  * tls_exitcode()
  244  *
  245  * Translate TLS_* error code to an error code from sysexits.h
  246  */
  247 int tls_exitcode(int tls_error_code);
  248 
  249 #endif