* this program. If not, see <http://www.gnu.org/licenses/>.
*/
+/**
+ * @page conn Connection Library
+ *
+ * Manage external connections.
+ *
+ * -# @subpage conn_globals
+ * -# @subpage conn_getdomain
+ * -# @subpage conn_sasl
+ * -# @subpage conn_sasl_plain
+ * -# @subpage conn_socket
+ * -# @subpage conn_ssl
+ * -# @subpage conn_ssl_gnutls
+ * -# @subpage conn_tunnel
+ */
+
#ifndef _CONN_CONN_H
#define _CONN_CONN_H
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
+/**
+ * @page conn_globals Connection Global Variables
+ *
+ * These global variables are private to the connection library.
+ *
+ * | Global Variable | NeoMutt Config
+ * | :--------------------- | :------------------------
+ * | #CertificateFile | $certificate_file
+ * | #ConnectTimeout | $connect_timeout
+ * | #EntropyFile | $entropy_file
+ * | #Preconnect | $preconnect
+ * | #SslCaCertificatesFile | $ssl_ca_certificates_file
+ * | #SslCiphers | $ssl_ciphers
+ * | #SslClientCert | $ssl_client_cert
+ * | #SslMinDhPrimeBits | $ssl_min_dh_prime_bits
+ * | #Tunnel | $tunnel
+ */
+
#include "config.h"
short ConnectTimeout; /**< Config: $connect_timeout */
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
+/**
+ * @page conn_getdomain DNS lookups
+ *
+ * DNS lookups
+ *
+ * | Function | Description
+ * | :----------------- | :-----------------------------------
+ * | getdnsdomainname() | Lookup the host's name using DNS
+ */
+
#include "config.h"
#include <netdb.h>
#include <string.h>
#include "lib/memory.h"
#include "lib/string2.h"
+/**
+ * getdnsdomainname - Lookup the host's name using DNS
+ * @param d Buffer for the result
+ * @param len Length of the buffer
+ * @retval 0 Success
+ * @retval -1 Error
+ */
int getdnsdomainname(char *d, size_t len)
{
int ret = -1;
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/* common SASL helper routines */
-/* SASL can stack a protection layer on top of an existing connection.
- * To handle this, we store a saslconn_t in conn->sockdata, and write
- * wrappers which en/decode the read/write stream, then replace sockdata
- * with an embedded copy of the old sockdata and call the underlying
- * functions (which we've also preserved). I thought about trying to make
- * a general stackable connection system, but it seemed like overkill -
- * something is wrong if we have 15 filters on top of a socket. Anyway,
- * anything else which wishes to stack can use the same method. The only
- * disadvantage is we have to write wrappers for all the socket methods,
- * even if we only stack over read and write. Thinking about it, the
- * abstraction problem is that there is more in Connection than there
- * needs to be. Ideally it would have only (void*)data and methods. */
+/**
+ * @page conn_sasl SASL authentication support
+ *
+ * SASL can stack a protection layer on top of an existing connection. To
+ * handle this, we store a saslconn_t in conn->sockdata, and write wrappers
+ * which en/decode the read/write stream, then replace sockdata with an
+ * embedded copy of the old sockdata and call the underlying functions (which
+ * we've also preserved). I thought about trying to make a general stackable
+ * connection system, but it seemed like overkill - something is wrong if we
+ * have 15 filters on top of a socket. Anyway, anything else which wishes to
+ * stack can use the same method. The only disadvantage is we have to write
+ * wrappers for all the socket methods, even if we only stack over read and
+ * write. Thinking about it, the abstraction problem is that there is more in
+ * Connection than there needs to be. Ideally it would have only (void*)data
+ * and methods.
+ *
+ * | Function | Description
+ * | :--------------------- | :-----------------------------------
+ * | mutt_sasl_client_new() | wrapper for sasl_client_new
+ * | mutt_sasl_done() | Invoke when processing is complete.
+ * | mutt_sasl_interact() | Perform an SASL interaction with the user
+ * | mutt_sasl_setup_conn() | Set up an SASL connection
+ */
#include "config.h"
#include <errno.h>
static sasl_secret_t *secret_ptr = NULL;
+/**
+ * getnameinfo_err - Convert a getaddrinfo() error code into an SASL error code
+ * @param ret getaddrinfo() error code, e.g. EAI_AGAIN
+ * @retval int SASL error code, e.g. SASL_FAIL
+ */
static int getnameinfo_err(int ret)
{
int err;
/**
* iptostring - Convert IP Address to string
+ * @param addr IP address
+ * @param addrlen Size of addr struct
+ * @param out Buffer for result
+ * @param outlen Length of buffer
+ * @retval int SASL error code, e.g. SASL_BADPARAM
*
* utility function, copied from sasl2 sample code
*/
/**
* mutt_sasl_cb_log - callback to log SASL messages
+ * @param context Supplied context, always NULL
+ * @param priority Debug level
+ * @param message Message
+ * @retval int SASL_OK, always
*/
static int mutt_sasl_cb_log(void *context, int priority, const char *message)
{
/**
* mutt_sasl_start - Initialise SASL library
+ * @retval int SASL error code, e.g. SASL_OK
*
* Call before doing an SASL exchange - initialises library (if necessary).
*/
/**
* mutt_sasl_cb_authname - callback to retrieve authname or user from Account
+ * @param[in] context Account
+ * @param[in] id Field to get. SASL_CB_USER or SASL_CB_AUTHNAME
+ * @param[out] result Resulting string
+ * @param[out] len Length of result
+ * @retval int SASL error code, e.g. SASL_FAIL
*/
static int mutt_sasl_cb_authname(void *context, int id, const char **result, unsigned *len)
{
return SASL_OK;
}
+/**
+ * mutt_sasl_cb_pass - SASL callback function to get password
+ * @param[in] conn Connection to a server
+ * @param[in] context Account
+ * @param[in] id SASL_CB_PASS
+ * @param[out] psecret SASL secret
+ * @retval int SASL error code, e.g SASL_FAIL
+ */
static int mutt_sasl_cb_pass(sasl_conn_t *conn, void *context, int id, sasl_secret_t **psecret)
{
struct Account *account = (struct Account *) context;
return SASL_OK;
}
+/**
+ * mutt_sasl_get_callbacks - Get the SASL callback functions
+ * @param account Account to associate with callbacks
+ * @retval ptr Array of callback functions
+ */
static sasl_callback_t *mutt_sasl_get_callbacks(struct Account *account)
{
sasl_callback_t *callback = NULL;
/**
* mutt_sasl_conn_open - empty wrapper for underlying open function
+ * @param conn Connection to the server
+ * @retval 0 Success
+ * @retval -1 Error
*
* We don't know in advance that a connection will use SASL, so we replace
* conn's methods with sasl methods when authentication is successful, using
/**
* mutt_sasl_conn_close - close SASL connection
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error
*
* Calls underlying close function and disposes of the sasl_conn_t object, then
* restores connection to pre-sasl state
return rc;
}
+/**
+ * mutt_sasl_conn_read - Read data from an SASL connection
+ * @param conn Connection to a server
+ * @param buf Buffer to store the data
+ * @param len Number of bytes to read
+ * @retval >0 Success, number of bytes read
+ * @retval -1 Error, see errno
+ */
static int mutt_sasl_conn_read(struct Connection *conn, char *buf, size_t len)
{
struct SaslData *sasldata = NULL;
return rc;
}
+/**
+ * mutt_sasl_conn_write - Write to an SASL connection
+ * @param conn Connection to a server
+ * @param buf Buffer to store the data
+ * @param len Number of bytes to read
+ * @retval >0 Success, number of bytes read
+ * @retval -1 Error, see errno
+ */
static int mutt_sasl_conn_write(struct Connection *conn, const char *buf, size_t len)
{
struct SaslData *sasldata = NULL;
return -1;
}
+/**
+ * mutt_sasl_conn_poll - Check an SASL connection for data
+ * @param conn Connection to a server
+ * @param wait_secs How long to wait for a response
+ * @retval >0 There is data to read
+ * @retval 0 Read would block
+ * @retval -1 Connection doesn't support polling
+ */
static int mutt_sasl_conn_poll(struct Connection *conn, time_t wait_secs)
{
struct SaslData *sasldata = conn->sockdata;
/**
* mutt_sasl_client_new - wrapper for sasl_client_new
+ * @param conn Connection to a server
+ * @param saslconn SASL connection
+ * @retval 0 Success
+ * @retval -1 Error
*
* which also sets various security properties. If this turns out to be fine
* for POP too we can probably stop exporting mutt_sasl_get_callbacks().
return 0;
}
+/**
+ * mutt_sasl_interact - Perform an SASL interaction with the user
+ * @param interaction Details of interaction
+ * @retval int SASL error code: SASL_OK or SASL_FAIL
+ *
+ * An example interaction might be asking the user for a password.
+ */
int mutt_sasl_interact(sasl_interact_t *interaction)
{
char prompt[SHORT_STRING];
/**
* mutt_sasl_setup_conn - Set up an SASL connection
+ * @param conn Connection to a server
+ * @param saslconn SASL connection
*
- * replace connection methods, sockdata with SASL wrappers, for protection
+ * Replace connection methods, sockdata with SASL wrappers, for protection
* layers. Also get ssf, as a fastpath for the read/write methods.
*/
void mutt_sasl_setup_conn(struct Connection *conn, sasl_conn_t *saslconn)
/*
* mutt_sasl_done - Invoke when processing is complete.
+ *
* This is a cleanup function, used to free all memory used by the library.
* Invoke when processing is complete.
*/
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
+/**
+ * @page conn_sasl_plain SASL plain authentication support
+ *
+ * SASL plain authentication support
+ *
+ * | Function | Description
+ * | :-------------------- | :-----------------------------------
+ * | mutt_sasl_plain_msg() | Create an SASL command
+ */
+
#include "config.h"
#include <stdio.h>
#include "lib/base64.h"
#include "lib/string2.h"
+/**
+ * mutt_sasl_plain_msg - Create an SASL command
+ * @param buf Buffer to store the command
+ * @param buflen Length of the buffer
+ * @param cmd SASL command
+ * @param authz Authorisation
+ * @param user Username
+ * @param pass Password
+ * @retval >0 Success, number of chars in the command string
+ * @retval 0 Error
+ *
+ * authz, user, and pass can each be up to 255 bytes, making up for a 765 bytes
+ * string. Add the two NULL bytes in between plus one at the end and we get
+ * 768.
+ */
size_t mutt_sasl_plain_msg(char *buf, size_t buflen, const char *cmd,
const char *authz, const char *user, const char *pass)
{
- /* authz, user, and pass can each be up to 255 bytes, making up for a 765
- * bytes string. Add the two NULL bytes in between plus one at the end and we
- * get 768. */
char tmp[768];
size_t len;
size_t tmplen;
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
+/**
+ * @page conn_socket Low-level socket handling
+ *
+ * Low-level socket handling
+ *
+ * | Function | Description
+ * | :--------------------- | :-----------------------------------
+ * | mutt_socket_close() | Close a socket
+ * | mutt_socket_open() | Simple wrapper
+ * | mutt_socket_poll() | Checks whether reads would block
+ * | mutt_socket_readchar() | simple read buffering to speed things up
+ * | mutt_socket_readln_d() | Read a line from a socket
+ * | mutt_socket_write_d() | Write data to a socket
+ * | raw_socket_close() | Close a socket
+ * | raw_socket_open() | Open a socket
+ * | raw_socket_poll() | Checks whether reads would block
+ * | raw_socket_read() | Read data from a socket
+ * | raw_socket_write() | Write data to a socket
+ * | socket_new_conn() | allocate and initialise a new connection
+ */
+
#include "config.h"
#include <time.h>
#include <errno.h>
#include "ssl.h"
#endif
+/**
+ * socket_preconnect - Execute a command before opening a socket
+ * @retval 0 Success
+ * @retval >0 An errno, e.g. EPERM
+ */
static int socket_preconnect(void)
{
int rc;
/**
* socket_connect - set up to connect to a socket fd
+ * @param fd File descriptor to connect with
+ * @param sa Address info
+ * @retval 0 Success
+ * @retval >0 An errno, e.g. EPERM
+ * @retval -1 Error
*/
static int socket_connect(int fd, struct sockaddr *sa)
{
/**
* mutt_socket_open - Simple wrapper
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error
*/
int mutt_socket_open(struct Connection *conn)
{
return rc;
}
+/**
+ * mutt_socket_close - Close a socket
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error
+ */
int mutt_socket_close(struct Connection *conn)
{
int rc = -1;
return rc;
}
+/**
+ * mutt_socket_write_d - Write data to a socket
+ * @param conn Connection to a server
+ * @param buf Buffer with data to write
+ * @param len Length of data to write
+ * @param dbg Debug level for logging
+ * @retval >0 Number of bytes written
+ * @retval -1 Error
+ */
int mutt_socket_write_d(struct Connection *conn, const char *buf, int len, int dbg)
{
int rc;
}
/**
- * mutt_socket_poll - poll whether reads would block
+ * mutt_socket_poll - Checks whether reads would block
+ * @param conn Connection to a server
+ * @param wait_secs How long to wait for a response
* @retval >0 There is data to read
* @retval 0 Read would block
* @retval -1 Connection doesn't support polling
/**
* mutt_socket_readchar - simple read buffering to speed things up
+ * @param[in] conn Connection to a server
+ * @param[out] c Character that was read
+ * @retval 1 Success
+ * @retval -1 Error
*/
int mutt_socket_readchar(struct Connection *conn, char *c)
{
return 1;
}
+/**
+ * mutt_socket_readln_d - Read a line from a socket
+ * @param buf Buffer to store the line
+ * @param buflen Length of data to write
+ * @param conn Connection to a server
+ * @param dbg Debug level for logging
+ * @retval >0 Success, number of bytes read
+ * @retval -1 Error
+ */
int mutt_socket_readln_d(char *buf, size_t buflen, struct Connection *conn, int dbg)
{
char ch;
/**
* socket_new_conn - allocate and initialise a new connection
+ * @retval ptr New Connection
*/
struct Connection *socket_new_conn(void)
{
return conn;
}
+/**
+ * raw_socket_close - Close a socket
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error, see errno
+ */
int raw_socket_close(struct Connection *conn)
{
return close(conn->fd);
}
+/**
+ * raw_socket_read - Read data from a socket
+ * @param conn Connection to a server
+ * @param buf Buffer to store the data
+ * @param len Number of bytes to read
+ * @retval >0 Success, number of bytes read
+ * @retval -1 Error, see errno
+ */
int raw_socket_read(struct Connection *conn, char *buf, size_t len)
{
int rc;
return rc;
}
+/**
+ * raw_socket_write - Write data to a socket
+ * @param conn Connection to a server
+ * @param buf Buffer to read into
+ * @param count Number of bytes to read
+ * @retval >0 Success, number of bytes written
+ * @retval -1 Error, see errno
+ */
int raw_socket_write(struct Connection *conn, const char *buf, size_t count)
{
int rc;
return rc;
}
+/**
+ * raw_socket_poll - Checks whether reads would block
+ * @param conn Connection to a server
+ * @param wait_secs How long to wait for a response
+ * @retval >0 There is data to read
+ * @retval 0 Read would block
+ * @retval -1 Connection doesn't support polling
+ */
int raw_socket_poll(struct Connection *conn, time_t wait_secs)
{
fd_set rfds;
}
}
+/**
+ * raw_socket_open - Open a socket
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error
+ */
int raw_socket_open(struct Connection *conn)
{
int rc;
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
+/**
+ * @page conn_ssl Handling of OpenSSL encryption
+ *
+ * Handling of OpenSSL encryption
+ *
+ * | Function | Description
+ * | :---------------------- | :-----------------------------------
+ * | mutt_ssl_socket_setup() | Set up the socket multiplexor
+ * | mutt_ssl_starttls() | Negotiate TLS over an already opened connection
+ */
+
#include "config.h"
#include <errno.h>
#include <limits.h>
/**
* ssl_load_certificates - Load certificates and filter out the expired ones
+ * @param ctx SSL context
+ * @retval 1 Success
+ * @retval 0 Error
*
* ssl certificate verification can behave strangely if there are expired certs
* loaded into the trusted store. This function filters out expired certs.
return rv;
}
+/**
+ * ssl_set_verify_partial - Allow verification using partial chains (with no root)
+ * @param ctx SSL context
+ * @retval 0 Success
+ * @retval -1 Error
+ */
static int ssl_set_verify_partial(SSL_CTX *ctx)
{
int rv = 0;
return rv;
}
+/**
+ * add_entropy - Add a source of random numbers
+ * @param file Random device
+ * @retval >0 Success, number of bytes read from the source
+ * @retval -1 Error
+ */
static int add_entropy(const char *file)
{
struct stat st;
return n;
}
+/**
+ * ssl_err - Display an SSL error message
+ * @param data SSL socket data
+ * @param err SSL error code
+ */
static void ssl_err(struct SslSockData *data, int err)
{
int e = SSL_get_error(data->ssl, err);
#endif
}
+/**
+ * ssl_dprint_err_stack - Dump the SSL error stack (DEBUG only)
+ */
static void ssl_dprint_err_stack(void)
{
#ifdef DEBUG
#endif
}
+/**
+ * ssl_passwd_cb - Callback to get a password
+ * @param buf Buffer for the password
+ * @param size Length of the buffer
+ * @param rwflag 0 if writing, 1 if reading (UNUSED)
+ * @param userdata Account whose password is requested
+ * @retval >0 Success, number of chars written to buf
+ * @retval 0 Error
+ */
static int ssl_passwd_cb(char *buf, int size, int rwflag, void *userdata)
{
struct Account *account = (struct Account *) userdata;
return snprintf(buf, size, "%s", account->pass);
}
+/**
+ * ssl_socket_open_err - Error callback for opening an SSL connection
+ * @param conn Connection to a server
+ * @retval -1 Always
+ */
static int ssl_socket_open_err(struct Connection *conn)
{
mutt_error(_("SSL disabled due to the lack of entropy"));
return -1;
}
+/**
+ * ssl_socket_close - Close an SSL connection
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error, see errno
+ */
static int ssl_socket_close(struct Connection *conn)
{
struct SslSockData *data = conn->sockdata;
return raw_socket_close(conn);
}
+/**
+ * x509_get_part - Retrieve from X509 data
+ * @param name Name of data to retrieve
+ * @param nid ID of the item to retrieve
+ * @retval ptr Retrieved data
+ *
+ * The returned pointer is to a static buffer, so it must not be free()'d.
+ */
static char *x509_get_part(X509_NAME *name, int nid)
{
static char ret[SHORT_STRING];
return ret;
}
+/**
+ * x509_fingerprint - Generate a fingerprint for an X509 certificate
+ * @param s Buffer for fingerprint
+ * @param l Length of buffer
+ * @param cert Certificate
+ * @param hashfunc Hashing function
+ */
static void x509_fingerprint(char *s, int l, X509 *cert, const EVP_MD *(*hashfunc)(void) )
{
unsigned char md[EVP_MAX_MD_SIZE];
}
}
+/**
+ * asn1time_to_string - Convert a time to a string
+ * @param tm Time to convert
+ * @retval ptr Time string
+ *
+ * The returned pointer is to a static buffer, so it must not be free()'d.
+ */
static char *asn1time_to_string(ASN1_UTCTIME *tm)
{
static char buf[64];
return buf;
}
+/**
+ * compare_certificates - Compare two X509 certificated
+ * @param cert Certificate
+ * @param peercert Peer certificate
+ * @param peermd Peer certificate message digest
+ * @param peermdlen Length of peer certificate message digest
+ * @retval true Certificates match
+ * @retval false Certificates differ
+ */
static bool compare_certificates(X509 *cert, X509 *peercert,
unsigned char *peermd, unsigned int peermdlen)
{
return true;
}
+/**
+ * check_certificate_expiration - Check if a certificate has expired
+ * @param peercert Certificate to check
+ * @param silent If true, don't notify the user if the certificate has expired
+ * @retval true Certificate is valid
+ * @retval false Certificate has expired (or hasn't yet become valid)
+ */
static bool check_certificate_expiration(X509 *peercert, bool silent)
{
if (option(OPT_SSL_VERIFY_DATES) != MUTT_NO)
/**
* hostname_match - Does the hostname match the certificate
+ * @param hostname Hostname
+ * @param certname Certificate
+ * @retval true Hostname matches the certificate
*/
static bool hostname_match(const char *hostname, const char *certname)
{
/**
* ssl_init - Initialist the SSL library
+ * @retval 0 Success
+ * @retval -1 Error
*
* OpenSSL library needs to be fed with sufficient entropy. On systems with
* /dev/urandom, this is done transparently by the library itself, on other
return 0;
}
+/**
+ * ssl_socket_read - Read data from an SSL socket
+ * @param conn Connection to a server
+ * @param buf Buffer to store the data
+ * @param len Number of bytes to read
+ * @retval >0 Success, number of bytes read
+ * @retval -1 Error, see errno
+ */
static int ssl_socket_read(struct Connection *conn, char *buf, size_t len)
{
struct SslSockData *data = conn->sockdata;
return rc;
}
+/**
+ * ssl_socket_write - Write data to an SSL socket
+ * @param conn Connection to a server
+ * @param buf Buffer to read into
+ * @param len Number of bytes to read
+ * @retval >0 Success, number of bytes written
+ * @retval -1 Error, see errno
+ */
static int ssl_socket_write(struct Connection *conn, const char *buf, size_t len)
{
struct SslSockData *data = conn->sockdata;
return rc;
}
+/**
+ * ssl_get_client_cert - Get the client certificate for an SSL connection
+ * @param ssldata SSL socket data
+ * @param conn Connection to a server
+ */
static void ssl_get_client_cert(struct SslSockData *ssldata, struct Connection *conn)
{
if (SslClientCert)
}
}
+/**
+ * tls_close - Close a TLS Connection
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error, see errno
+ */
static int tls_close(struct Connection *conn)
{
int rc;
return rc;
}
+/**
+ * check_certificate_cache - Is the X509 Certificate in the cache?
+ * @param peercert Certificate
+ * @retval true Certificate is in the cache
+ */
static bool check_certificate_cache(X509 *peercert)
{
unsigned char peermd[EVP_MAX_MD_SIZE];
return false;
}
+/**
+ * check_certificate_file - Read and check a certificate file
+ * @param peercert Certificate
+ * @retval 1 Certificate is valid
+ * @retval 0 Error, or certificate is invalid
+ */
static int check_certificate_file(X509 *peercert)
{
unsigned char peermd[EVP_MAX_MD_SIZE];
/**
* check_host - Check the host on the certificate
+ * @param x509cert Certificate
+ * @param hostname Hostname
+ * @param err Buffer for error message
+ * @param errlen Length of buffer
+ * @retval 1 Hostname matches the certificate
+ * @retval 0 Error
*/
static int check_host(X509 *x509cert, const char *hostname, char *err, size_t errlen)
{
return rc;
}
+/**
+ * check_certificate_by_digest - Validate a certificate by its digest
+ * @param peercert Certificate
+ * @retval 1 Certificate is valid
+ * @retval 0 Error
+ */
static int check_certificate_by_digest(X509 *peercert)
{
return check_certificate_expiration(peercert, false) && check_certificate_file(peercert);
}
+/**
+ * ssl_cache_trusted_cert - Cache a trusted certificate
+ * @param c Certificate
+ * @retval >0 Number of elements in the cache
+ * @retval 0 Error
+ */
static int ssl_cache_trusted_cert(X509 *c)
{
mutt_debug(1, "ssl_cache_trusted_cert: trusted\n");
return (sk_X509_push(SslSessionCerts, X509_dup(c)));
}
+/**
+ * interactive_check_cert - Ask the user if a certificate is valid
+ * @param cert Certificate
+ * @param idx Place of certificate in the chain
+ * @param len Length of the certificate chain
+ * @param ssl SSL state
+ * @param allow_always If certificate may be always allowed
+ * @retval true User selected 'skip'
+ * @retval false Otherwise
+ */
static int interactive_check_cert(X509 *cert, int idx, int len, SSL *ssl, int allow_always)
{
static const int part[] = {
}
/**
- * ssl_verify_callback - certificate verification callback
+ * ssl_verify_callback - Certificate verification callback
+ * @param preverify_ok If true, don't question the user if they skipped verification
+ * @param ctx X509 store context
+ * @retval true Certificate is valid
+ * @retval false Error, or Certificate is invalid
*
* called for each certificate in the chain sent by the peer, starting from the
* root; returning 1 means that the given certificate is trusted, returning 0
/**
* ssl_negotiate - Attempt to negotiate SSL over the wire
+ * @param conn Connection to a server
+ * @param ssldata SSL socket data
+ * @retval 0 Success
+ * @retval -1 Error
*
* After SSL state has been initialized, attempt to negotiate SSL over the
* wire, including certificate checks.
return 0;
}
+/**
+ * ssl_socket_open - Open an SSL socket
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error
+ */
static int ssl_socket_open(struct Connection *conn)
{
struct SslSockData *data = NULL;
/**
* mutt_ssl_starttls - Negotiate TLS over an already opened connection
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error
*
* TODO: Merge this code better with ssl_socket_open.
*/
return -1;
}
+/**
+ * mutt_ssl_socket_setup - Set up the socket multiplexor
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error
+ */
int mutt_ssl_socket_setup(struct Connection *conn)
{
if (ssl_init() < 0)
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
+/**
+ * @page conn_ssl_gnutls Handling of GnuTLS encryption
+ *
+ * Handling of GnuTLS encryption
+ *
+ * | Function | Description
+ * | :---------------------- | :-----------------------------------
+ * | mutt_ssl_socket_setup() | Set up SSL socket mulitplexor
+ * | mutt_ssl_starttls() | Set up TLS multiplexor
+ */
+
#include "config.h"
#include <gnutls/gnutls.h>
#include <gnutls/x509.h>
gnutls_certificate_credentials_t xcred;
};
+/**
+ * tls_init - Set up Gnu TLS
+ * @retval 0 Success
+ * @retval -1 Error
+ */
static int tls_init(void)
{
static bool init_complete = false;
return 0;
}
+/**
+ * tls_socket_read - Read data from a TLS socket
+ * @param conn Connection to a server
+ * @param buf Buffer to store the data
+ * @param len Number of bytes to read
+ * @retval >0 Success, number of bytes read
+ * @retval -1 Error, see errno
+ */
static int tls_socket_read(struct Connection *conn, char *buf, size_t len)
{
struct TlsSockData *data = conn->sockdata;
return ret;
}
+/**
+ * tls_socket_write - Write data to a TLS socket
+ * @param conn Connection to a server
+ * @param buf Buffer to read into
+ * @param len Number of bytes to read
+ * @retval >0 Success, number of bytes written
+ * @retval -1 Error, see errno
+ */
static int tls_socket_write(struct Connection *conn, const char *buf, size_t len)
{
struct TlsSockData *data = conn->sockdata;
return sent;
}
+/**
+ * tls_socket_close - Close a TLS socket
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error, see errno
+ */
static int tls_socket_close(struct Connection *conn)
{
struct TlsSockData *data = conn->sockdata;
return raw_socket_close(conn);
}
+/**
+ * tls_starttls_close - Close a TLS connection
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error, see errno
+ */
static int tls_starttls_close(struct Connection *conn)
{
int rc;
/**
* tls_verify_peers - wrapper for gnutls_certificate_verify_peers
+ * @param tlsstate TLS state
+ * @retval 0 Success
+ * @retval >0 Error, e.g. GNUTLS_CERT_INVALID
*
* wrapper with sanity-checking
*/
return status;
}
+/**
+ * tls_fingerprint - Create a fingerprint of a TLS Certificate
+ * @param algo Fingerprint algorithm, e.g. GNUTLS_MAC_SHA256
+ * @param s Buffer for the fingerprint
+ * @param l Length of the buffer
+ * @param data Certificate
+ */
static void tls_fingerprint(gnutls_digest_algorithm_t algo, char *s, int l,
const gnutls_datum_t *data)
{
}
}
+/**
+ * tls_check_stored_hostname - Does the hostname match a stored certificate?
+ * @param cert Certificate
+ * @param hostname Hostname
+ * @retval 1 Hostname match found
+ * @retval 0 Error, or no match
+ */
static int tls_check_stored_hostname(const gnutls_datum_t *cert, const char *hostname)
{
char buf[80];
}
/**
- * tls_compare_certificates - Compare certificates
+ * tls_compare_certificates - Compare certificates against CertificateFile
+ * @param peercert Certificate
+ * @retval 1 Certificate matches file
+ * @retval 0 Error, or no match
*/
static int tls_compare_certificates(const gnutls_datum_t *peercert)
{
return 0;
}
+/**
+ * tls_check_preauth - Prepare a certificate for authentication
+ * @param[in] certdata List of GnuTLS certificates
+ * @param[in] certstat GnuTLS certificate status
+ * @param[in] hostname Hostname
+ * @param[in] chainidx Index in the certificate chain
+ * @param[out] certerr Result, e.g. #CERTERR_VALID
+ * @param[out] savedcert 1 if certificate has been saved
+ * @retval 0 Success
+ * @retval -1 Error
+ */
static int tls_check_preauth(const gnutls_datum_t *certdata,
gnutls_certificate_status_t certstat, const char *hostname,
int chainidx, int *certerr, int *savedcert)
return -1;
}
+/**
+ * tls_make_date - Create a TLS date string
+ * @param t Time to convert
+ * @param s Buffer for the string
+ * @param len Length of the buffer
+ * @retval ptr Pointer to s
+ */
static char *tls_make_date(time_t t, char *s, size_t len)
{
struct tm *l = gmtime(&t);
return (done == 2);
}
+/**
+ * tls_check_certificate - Check a connection's certificate
+ * @param conn Connection to a server
+ * @retval >0 Certificate is valid
+ * @retval 0 Error, or certificate is invalid
+ */
static int tls_check_certificate(struct Connection *conn)
{
struct TlsSockData *data = conn->sockdata;
return rc;
}
+/**
+ * tls_get_client_cert - Get the client certificate for a TLS connection
+ * @param conn Connection to a server
+ */
static void tls_get_client_cert(struct Connection *conn)
{
struct TlsSockData *data = conn->sockdata;
}
#ifdef HAVE_GNUTLS_PRIORITY_SET_DIRECT
+/**
+ * tls_set_priority - Set TLS algorithm priorities
+ * @param data TLS socket data
+ * @retval 0 Success
+ * @retval -1 Error
+ */
static int tls_set_priority(struct TlsSockData *data)
{
size_t nproto = 4;
/**
* tls_negotiate - Negotiate TLS connection
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error
*
* After TLS state has been initialized, attempt to negotiate TLS over the
* wire, including certificate checks.
gnutls_dh_set_prime_bits(data->state, SslMinDhPrimeBits);
}
- /*
- gnutls_set_cred (data->state, GNUTLS_ANON, NULL);
-*/
+ /* gnutls_set_cred (data->state, GNUTLS_ANON, NULL); */
gnutls_credentials_set(data->state, GNUTLS_CRD_CERTIFICATE, data->xcred);
return -1;
}
+/**
+ * tls_socket_open - Open a TLS socket
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error
+ */
static int tls_socket_open(struct Connection *conn)
{
if (raw_socket_open(conn) < 0)
return 0;
}
+/**
+ * mutt_ssl_socket_setup - Set up SSL socket mulitplexor
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error
+ */
int mutt_ssl_socket_setup(struct Connection *conn)
{
if (tls_init() < 0)
return 0;
}
+/**
+ * mutt_ssl_starttls - Set up TLS multiplexor
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error
+ */
int mutt_ssl_starttls(struct Connection *conn)
{
if (tls_init() < 0)
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
+/**
+ * @page conn_tunnel Support for network tunnelling
+ *
+ * Support for network tunnelling
+ *
+ * | Function | Description
+ * | :------------------------- | :-----------------------------------
+ * | mutt_tunnel_socket_setup() | setups tunnel connection functions.
+ */
+
#include "config.h"
#include <errno.h>
#include <fcntl.h>
int writefd;
};
+/**
+ * tunnel_socket_open - Open a tunnel socket
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error
+ */
static int tunnel_socket_open(struct Connection *conn)
{
struct TunnelData *tunnel = NULL;
return 0;
}
+/**
+ * tunnel_socket_close - Close a tunnel socket
+ * @param conn Connection to a server
+ * @retval 0 Success
+ * @retval -1 Error, see errno
+ */
static int tunnel_socket_close(struct Connection *conn)
{
struct TunnelData *tunnel = (struct TunnelData *) conn->sockdata;
return 0;
}
+/**
+ * tunnel_socket_read - Read data from a tunnel socket
+ * @param conn Connection to a server
+ * @param buf Buffer to store the data
+ * @param len Number of bytes to read
+ * @retval >0 Success, number of bytes read
+ * @retval -1 Error, see errno
+ */
static int tunnel_socket_read(struct Connection *conn, char *buf, size_t len)
{
struct TunnelData *tunnel = (struct TunnelData *) conn->sockdata;
return rc;
}
+/**
+ * tunnel_socket_write - Write data to a tunnel socket
+ * @param conn Connection to a server
+ * @param buf Buffer to read into
+ * @param len Number of bytes to read
+ * @retval >0 Success, number of bytes written
+ * @retval -1 Error, see errno
+ */
static int tunnel_socket_write(struct Connection *conn, const char *buf, size_t len)
{
struct TunnelData *tunnel = (struct TunnelData *) conn->sockdata;
return rc;
}
+/**
+ * tunnel_socket_poll - Checks whether tunnel reads would block
+ * @param conn Connection to a server
+ * @param wait_secs How long to wait for a response
+ * @retval >0 There is data to read
+ * @retval 0 Read would block
+ * @retval -1 Connection doesn't support polling
+ */
static int tunnel_socket_poll(struct Connection *conn, time_t wait_secs)
{
struct TunnelData *tunnel = (struct TunnelData *) conn->sockdata;
* This module defines the user-visible header cache API, which is used within
* neomutt to cache and restore mail header data.
*
+ * @note This library isn't completely independent.
+ * Dependencies:
+ * - \ref lib
+ * - Global variables
+ * * Charset
+ * * Charset_is_utf8
+ * * HeaderCacheBackend
+ * * HeaderCachePageSize
+ * * Options
+ * * SpamList
+ * * NoSpamList
+ * - Neomutt functions
+ * * mutt_convert_string()
+ * * mutt_encode_path()
+ * * mutt_new_body()
+ * * mutt_new_envelope()
+ * * mutt_sleep()
+ * * mx_lock_file()
+ * * mx_unlock_file()
+ *
* @subpage hc_hcache
*
* Backends:
*
* Each source file in the library provides a group of related functions.
*
- * The library is self-contained -- some files may depend on others in the
- * library, but none depends on source from outside.
+ * @note The library is self-contained -- some files may depend on others in
+ * the library, but none depends on source from outside.
*
* -# @subpage base64
* -# @subpage buffer
/**
* mutt_list_insert_after - Insert a string after a given ListNode
* @param h Head of the List
- * @parem n ListNode after which the string will be inserted
+ * @param n ListNode after which the string will be inserted
* @param s String to insert
* @retval ptr Newly created ListNode containing the string
*/
/**
* mutt_list_find - Find a string in a List
- * @param h Head of the List
- * @param s String to find
+ * @param h Head of the List
+ * @param data String to find
* @retval ptr ListNode containing the string
* @retval NULL if the string isn't found
*/
projects / neomutt / commitdiff