private.h File Reference

POP network mailbox. More...

#include <stdbool.h>
#include <time.h>
#include "conn/lib.h"

Include dependency graph for private.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	PopCache
	POP-specific email cache. More...
struct	PopAuth
	POP authentication multiplexor. More...

Macros
#define	POP_PORT   110
	Default port for POP3.
#define	POP_SSL_PORT   995
	Default port for POP3 over SSL.
#define	POP_CACHE_LEN   10
	Number of entries in the POP cache hash table.
#define	POP_CMD_RESPONSE   512
	Maximum length of POP server response (per RFC1939).

Typedefs
typedef int(*	pop_fetch_t) (const char *str, void *data)

Enumerations
enum	PopStatus { POP_NONE = 0 , POP_CONNECTED , POP_DISCONNECTED }
	POP server responses. More...
enum	PopAuthRes { POP_A_SUCCESS = 0 , POP_A_SOCKET , POP_A_FAILURE , POP_A_UNAVAIL }
	POP authentication responses. More...

Functions
bool	pop_auth_is_valid (const char *authenticator)
	Check if string is a valid pop authentication method.
int	pop_authenticate (struct PopAccountData *adata)
	Authenticate with a POP server.
void	pop_apop_timestamp (struct PopAccountData *adata, char *buf)
	Get the server timestamp for APOP authentication.
int	pop_parse_path (const char *path, struct ConnAccount *acct)
	Parse a POP mailbox name.
int	pop_connect (struct PopAccountData *adata)
	Open connection.
int	pop_open_connection (struct PopAccountData *adata)
	Open connection and authenticate.
int	pop_query (struct PopAccountData *adata, char *buf, size_t buflen, char *msg)
	Send data from buffer and receive answer to the same buffer.
int	pop_fetch_data (struct PopAccountData *adata, const char *query, struct Progress *progress, pop_fetch_t callback, void *data)
	Read Headers with callback function.
int	pop_reconnect (struct Mailbox *m)
	Reconnect and verify indexes if connection was lost.
void	pop_logout (struct Mailbox *m)
	Logout from a POP server.
const char *	pop_get_field (enum ConnAccountField field, void *gf_data)
	Get connection login credentials - Implements ConnAccount::get_field() -.

Detailed Description

POP network mailbox.

Authors

• Vsevolod Volkov
• Richard Russon

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file private.h.

Macro Definition Documentation

POP_PORT

#define POP_PORT   110

Default port for POP3.

Definition at line 35 of file private.h.

POP_SSL_PORT

#define POP_SSL_PORT   995

Default port for POP3 over SSL.

Definition at line 36 of file private.h.

POP_CACHE_LEN

#define POP_CACHE_LEN   10

Number of entries in the POP cache hash table.

Definition at line 38 of file private.h.

POP_CMD_RESPONSE

#define POP_CMD_RESPONSE   512

Maximum length of POP server response (per RFC1939).

Definition at line 40 of file private.h.

Typedef Documentation

pop_fetch_t

typedef int(* pop_fetch_t) (const char *str, void *data)

Definition at line 106 of file private.h.

Enumeration Type Documentation

PopStatus

enum PopStatus

POP server responses.

Enumerator
POP_NONE	No connected to server.
POP_CONNECTED	Connected to server.
POP_DISCONNECTED	Disconnected from server.

Definition at line 45 of file private.h.

{
  POP_NONE = 0,     
  POP_CONNECTED,    
  POP_DISCONNECTED, 
};

PopAuthRes

enum PopAuthRes

POP authentication responses.

Enumerator
POP_A_SUCCESS	Authenticated successfully.
POP_A_SOCKET	Connection lost.
POP_A_FAILURE	Authentication failed.
POP_A_UNAVAIL	No valid authentication method.

Definition at line 55 of file private.h.

{
  POP_A_SUCCESS = 0, 
  POP_A_SOCKET,      
  POP_A_FAILURE,     
  POP_A_UNAVAIL,     
};

Function Documentation

pop_auth_is_valid()

bool pop_auth_is_valid

(

const char *

authenticator

)

Check if string is a valid pop authentication method.

Parameters

authenticator

Authenticator string to check

Return values

true	Argument is a valid auth method

Validate whether an input string is an accepted pop authentication method as defined by PopAuthenticators.

Definition at line 534 of file auth.c.

{
  for (size_t i = 0; i < countof(PopAuthenticators); i++)
  {
    const struct PopAuth *auth = &PopAuthenticators[i];
    if (auth->method && mutt_istr_equal(auth->method, authenticator))
      return true;
  }
 
  return false;
}

Here is the call graph for this function:

Here is the caller graph for this function:

pop_authenticate()

int pop_authenticate

(

struct PopAccountData *

adata

)

Authenticate with a POP server.

Parameters

adata

POP Account data

Return values

num	Result, e.g. POP_A_SUCCESS
0	Successful
-1	Connection lost
-2	Login failed
-3	Authentication cancelled

Definition at line 555 of file auth.c.

{
  struct ConnAccount *cac = &adata->conn->account;
  const struct PopAuth *authenticator = NULL;
  int attempts = 0;
  int rc = POP_A_UNAVAIL;
 
  if ((mutt_account_getuser(cac) < 0) || (cac->user[0] == '\0'))
  {
    return -3;
  }
 
  const struct Slist *c_pop_authenticators = cs_subset_slist(NeoMutt->sub, "pop_authenticators");
  const bool c_pop_auth_try_all = cs_subset_bool(NeoMutt->sub, "pop_auth_try_all");
  if (c_pop_authenticators && (c_pop_authenticators->count > 0))
  {
    /* Try user-specified list of authentication methods */
    struct ListNode *np = NULL;
    STAILQ_FOREACH(np, &c_pop_authenticators->head, entries)
    {
      mutt_debug(LL_DEBUG2, "Trying method %s\n", np->data);
      authenticator = PopAuthenticators;
 
      /* Walk the built-in authenticator table looking for a match */
      while (authenticator->authenticate)
      {
        if (!authenticator->method || mutt_istr_equal(authenticator->method, np->data))
        {
          rc = authenticator->authenticate(adata, np->data);
          if (rc == POP_A_SOCKET)
          {
            /* Connection dropped; try reconnecting and retrying once */
            switch (pop_connect(adata))
            {
              case 0:
              {
                rc = authenticator->authenticate(adata, np->data);
                break;
              }
              case -2:
                rc = POP_A_FAILURE;
                break;
              default:
                break;
            }
          }
 
          if (rc != POP_A_UNAVAIL)
            attempts++;
          if ((rc == POP_A_SUCCESS) || (rc == POP_A_SOCKET) ||
              ((rc == POP_A_FAILURE) && !c_pop_auth_try_all))
          {
            break;
          }
        }
        authenticator++;
      }
    }
  }
  else
  {
    /* Fall back to default: try every authenticator in order */
    mutt_debug(LL_DEBUG2, "Using any available method\n");
    authenticator = PopAuthenticators;
 
    while (authenticator->authenticate)
    {
      rc = authenticator->authenticate(adata, NULL);
      if (rc == POP_A_SOCKET)
      {
        switch (pop_connect(adata))
        {
          case 0:
          {
            rc = authenticator->authenticate(adata, NULL);
            break;
          }
          case -2:
            rc = POP_A_FAILURE;
            break;
          default:
            break;
        }
      }
 
      if (rc != POP_A_UNAVAIL)
        attempts++;
      if ((rc == POP_A_SUCCESS) || (rc == POP_A_SOCKET) ||
          ((rc == POP_A_FAILURE) && !c_pop_auth_try_all))
      {
        break;
      }
 
      authenticator++;
    }
  }
 
  /* Map internal result code to the caller's return values */
  switch (rc)
  {
    case POP_A_SUCCESS:
      return 0;
    case POP_A_SOCKET:
      return -1;
    case POP_A_UNAVAIL:
      if (attempts == 0)
        mutt_error(_("No authenticators available"));
      break;
 
    default:
      break;
  }
 
  return -2;
}

Here is the call graph for this function:

Here is the caller graph for this function:

pop_apop_timestamp()

void pop_apop_timestamp	(	struct PopAccountData *	adata,
		char *	buf )

Get the server timestamp for APOP authentication.

Parameters

adata	POP Account data
buf	Timestamp string

Definition at line 326 of file auth.c.

{
  char *p1 = NULL;
  char *p2 = NULL;
 
  FREE(&adata->timestamp);
 
  if ((p1 = strchr(buf, '<')) && (p2 = strchr(p1, '>')))
  {
    p2[1] = '\0';
    adata->timestamp = mutt_str_dup(p1);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

pop_parse_path()

int pop_parse_path	(	const char *	path,
		struct ConnAccount *	cac )

Parse a POP mailbox name.

Parameters

path	Path to parse
cac	Account to store details

Return values

0	success
-1	error

Split a POP path into host, port, username and password

Definition at line 82 of file lib.c.

{
  /* Defaults */
  cac->flags = 0;
  cac->type = MUTT_ACCT_TYPE_POP;
  cac->port = 0;
  cac->service = "pop";
  cac->get_field = pop_get_field;
 
  struct Url *url = url_parse(path);
 
  if (!url || ((url->scheme != U_POP) && (url->scheme != U_POPS)) ||
      !url->host || (account_from_url(cac, url) < 0))
  {
    url_free(&url);
    mutt_error(_("Invalid POP URL: %s"), path);
    return -1;
  }
 
  if (url->scheme == U_POPS)
    cac->flags |= MUTT_ACCT_SSL;
 
  struct servent *service = getservbyname((url->scheme == U_POP) ? "pop3" : "pop3s", "tcp");
  if (cac->port == 0)
  {
    if (service)
      cac->port = ntohs(service->s_port);
    else
      cac->port = (url->scheme == U_POP) ? POP_PORT : POP_SSL_PORT;
  }
 
  url_free(&url);
  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

pop_connect()

int pop_connect

(

struct PopAccountData *

adata

)

Open connection.

Parameters

adata

POP Account data

Return values

0	Successful
-1	Connection lost
-2	Invalid response

Definition at line 282 of file lib.c.

{
  char buf[1024] = { 0 };
 
  adata->status = POP_NONE;
  if ((mutt_socket_open(adata->conn) < 0) ||
      (mutt_socket_readln(buf, sizeof(buf), adata->conn) < 0))
  {
    mutt_error(_("Error connecting to server: %s"), adata->conn->account.host);
    return -1;
  }
 
  adata->status = POP_CONNECTED;
 
  if (!mutt_str_startswith(buf, "+OK"))
  {
    *adata->err_msg = '\0';
    pop_error(adata, buf);
    mutt_error("%s", adata->err_msg);
    return -2;
  }
 
  pop_apop_timestamp(adata, buf);
 
  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

pop_open_connection()

int pop_open_connection

(

struct PopAccountData *

adata

)

Open connection and authenticate.

Parameters

adata

POP Account data

Return values

0	Successful
-1	Connection lost
-2	Invalid command or execution error
-3	Authentication cancelled

Definition at line 317 of file lib.c.

{
  char buf[1024] = { 0 };
 
  int rc = pop_connect(adata);
  if (rc < 0)
    return rc;
 
  rc = pop_capabilities(adata, 0);
  if (rc == -1)
    goto err_conn;
  if (rc == -2)
    return -2;
 
#ifdef USE_SSL
  /* Attempt STLS if available and desired. */
  const bool c_ssl_force_tls = cs_subset_bool(NeoMutt->sub, "ssl_force_tls");
  if ((adata->conn->ssf == 0) && (adata->cmd_stls || c_ssl_force_tls))
  {
    if (c_ssl_force_tls)
      adata->use_stls = 2;
    if (adata->use_stls == 0)
    {
      enum QuadOption ans = query_quadoption(_("Secure connection with TLS?"),
                                             NeoMutt->sub, "ssl_starttls");
      if (ans == MUTT_ABORT)
        return -2;
      adata->use_stls = 1;
      if (ans == MUTT_YES)
        adata->use_stls = 2;
    }
    if (adata->use_stls == 2)
    {
      mutt_str_copy(buf, "STLS\r\n", sizeof(buf));
      rc = pop_query(adata, buf, sizeof(buf), NULL);
      // Clear any data after the STLS acknowledgement
      mutt_socket_empty(adata->conn);
      if (rc == -1)
        goto err_conn;
      if (rc != 0)
      {
        mutt_error("%s", adata->err_msg);
      }
      else if (mutt_ssl_starttls(adata->conn) != 0)
      {
        mutt_error(_("Could not negotiate TLS connection"));
        return -2;
      }
      else
      {
        /* recheck capabilities after STLS completes */
        rc = pop_capabilities(adata, 1);
        if (rc == -1)
          goto err_conn;
        if (rc == -2)
          return -2;
      }
    }
  }
 
  if (c_ssl_force_tls && (adata->conn->ssf == 0))
  {
    mutt_error(_("Encrypted connection unavailable"));
    return -2;
  }
#endif
 
  rc = pop_authenticate(adata);
  if (rc == -1)
    goto err_conn;
  if (rc == -3)
    mutt_clear_error();
  if (rc != 0)
    return rc;
 
  /* recheck capabilities after authentication */
  rc = pop_capabilities(adata, 2);
  if (rc == -1)
    goto err_conn;
  if (rc == -2)
    return -2;
 
  /* get total size of mailbox */
  mutt_str_copy(buf, "STAT\r\n", sizeof(buf));
  rc = pop_query(adata, buf, sizeof(buf), NULL);
  if (rc == -1)
    goto err_conn;
  if (rc == -2)
  {
    mutt_error("%s", adata->err_msg);
    return rc;
  }
 
  unsigned int n = 0;
  size_t size = 0;
  sscanf(buf, "+OK %u %zu", &n, &size);
  adata->size = size;
  return 0;
 
err_conn:
  adata->status = POP_DISCONNECTED;
  mutt_error(_("Server closed connection"));
  return -1;
}

Here is the call graph for this function:

Here is the caller graph for this function:

pop_query()

int pop_query	(	struct PopAccountData *	adata,
		char *	buf,
		size_t	buflen,
		char *	msg )

Send data from buffer and receive answer to the same buffer.

Parameters

adata	POP Account data
buf	Buffer to send/store data
buflen	Buffer length
msg	Progress message

Return values

0	Successful
-1	Connection lost
-2	Invalid command or execution error

Definition at line 467 of file lib.c.

{
  if (adata->status != POP_CONNECTED)
    return -1;
 
  /* print msg instead of real command */
  if (msg)
  {
    mutt_debug(MUTT_SOCK_LOG_CMD, "> %s", msg);
  }
 
  mutt_socket_send_d(adata->conn, buf, MUTT_SOCK_LOG_FULL);
 
  char *c = strpbrk(buf, " \r\n");
  if (c)
    *c = '\0';
  snprintf(adata->err_msg, sizeof(adata->err_msg), "%s: ", buf);
 
  if (mutt_socket_readln_d(buf, buflen, adata->conn, MUTT_SOCK_LOG_FULL) < 0)
  {
    adata->status = POP_DISCONNECTED;
    return -1;
  }
  if (mutt_str_startswith(buf, "+OK"))
    return 0;
 
  pop_error(adata, buf);
  return -2;
}

Here is the call graph for this function:

Here is the caller graph for this function:

pop_fetch_data()

int pop_fetch_data	(	struct PopAccountData *	adata,
		const char *	query,
		struct Progress *	progress,
		pop_fetch_t	callback,
		void *	data )

Read Headers with callback function.

Parameters

adata	POP Account data
query	POP query to send to server
progress	Progress bar
callback	Function called for each header read
data	Data to pass to the callback

Return values

0	Successful
-1	Connection lost
-2	Invalid command or execution error
-3	Error in callback(*line, *data)

This function calls callback(*line, *data) for each received line, callback(NULL, *data) if rewind(*data) needs, exits when fail or done.

Definition at line 512 of file lib.c.

{
  char buf[1024] = { 0 };
  long pos = 0;
  size_t lenbuf = 0;
 
  mutt_str_copy(buf, query, sizeof(buf));
  int rc = pop_query(adata, buf, sizeof(buf), NULL);
  if (rc < 0)
    return rc;
 
  char *inbuf = MUTT_MEM_MALLOC(sizeof(buf), char);
 
  while (true)
  {
    const int chunk = mutt_socket_readln_d(buf, sizeof(buf), adata->conn, MUTT_SOCK_LOG_FULL);
    if (chunk < 0)
    {
      adata->status = POP_DISCONNECTED;
      rc = -1;
      break;
    }
 
    char *p = buf;
    if (!lenbuf && (buf[0] == '.'))
    {
      if (buf[1] != '.')
        break;
      p++;
    }
 
    mutt_str_copy(inbuf + lenbuf, p, sizeof(buf));
    pos += chunk;
 
    /* cast is safe since we break out of the loop when chunk<=0 */
    if ((size_t) chunk >= sizeof(buf))
    {
      lenbuf += strlen(p);
    }
    else
    {
      progress_update(progress, pos, -1);
      if ((rc == 0) && (callback(inbuf, data) < 0))
        rc = -3;
      lenbuf = 0;
    }
 
    MUTT_MEM_REALLOC(&inbuf, lenbuf + sizeof(buf), char);
  }
 
  FREE(&inbuf);
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

pop_reconnect()

int pop_reconnect

(

struct Mailbox *

m

)

Reconnect and verify indexes if connection was lost.

Parameters

m

Mailbox

Return values

0	Success
-1	Error

Definition at line 610 of file lib.c.

{
  struct PopAccountData *adata = pop_adata_get(m);
 
  if (adata->status == POP_CONNECTED)
    return 0;
 
  while (true)
  {
    mutt_socket_close(adata->conn);
 
    int rc = pop_open_connection(adata);
    if (rc == 0)
    {
      struct Progress *progress = progress_new(MUTT_PROGRESS_NET, 0);
      progress_set_message(progress, _("Verifying message indexes..."));
 
      for (int i = 0; i < m->msg_count; i++)
      {
        struct PopEmailData *edata = pop_edata_get(m->emails[i]);
        edata->refno = -1;
      }
 
      rc = pop_fetch_data(adata, "UIDL\r\n", progress, check_uidl, m);
      progress_free(&progress);
      if (rc == -2)
      {
        mutt_error("%s", adata->err_msg);
      }
    }
 
    if (rc == 0)
      return 0;
 
    pop_logout(m);
 
    if (rc < -1)
      return -1;
 
    if (query_quadoption(_("Connection lost. Reconnect to POP server?"),
                         NeoMutt->sub, "pop_reconnect") != MUTT_YES)
    {
      return -1;
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

pop_logout()

void pop_logout

(

struct Mailbox *

m

)

Logout from a POP server.

Parameters

m

Mailbox

Definition at line 426 of file lib.c.

{
  struct PopAccountData *adata = pop_adata_get(m);
 
  if (adata->status == POP_CONNECTED)
  {
    int rc = 0;
    char buf[1024] = { 0 };
    mutt_message(_("Closing connection to POP server..."));
 
    if (m->readonly)
    {
      mutt_str_copy(buf, "RSET\r\n", sizeof(buf));
      rc = pop_query(adata, buf, sizeof(buf), NULL);
    }
 
    if (rc != -1)
    {
      mutt_str_copy(buf, "QUIT\r\n", sizeof(buf));
      rc = pop_query(adata, buf, sizeof(buf), NULL);
    }
 
    if (rc < 0)
      mutt_debug(LL_DEBUG1, "Error closing POP connection\n");
 
    mutt_clear_error();
  }
 
  adata->status = POP_DISCONNECTED;
}

Here is the call graph for this function:

Here is the caller graph for this function: