Gumdrop POP3 Server

← Back to Main Page

Gumdrop provides a complete POP3 server implementation following RFC 1939 with modern extensions. POP3 (Post Office Protocol version 3) provides simple, download-oriented mailbox access—clients retrieve messages and optionally delete them from the server. Like all Gumdrop protocol implementations, the POP3 server uses the event-driven, non-blocking architecture.

Contents

• Protocol Support
• Extensions
• Authentication
• Mailbox Integration
• Configuration
• Security

Protocol Support

The POP3 server implements the base protocol as defined in RFC 1939 with extensions from RFC 2449 (POP3 Extension Mechanism) and RFC 5034 (SASL Authentication).

Protocol States

POP3 sessions progress through three states:

• AUTHORIZATION - initial state; client must authenticate using USER/PASS, APOP, or AUTH with a SASL mechanism
• TRANSACTION - authenticated; client can retrieve messages, mark deletions, and query mailbox status
• UPDATE - after QUIT; server commits deletions and releases the mailbox lock

Required Commands (RFC 1939)

• USER/PASS - basic username/password authentication
• STAT - returns message count and total size
• LIST - lists messages with their sizes
• RETR - retrieves a complete message
• DELE - marks a message for deletion
• NOOP - keeps connection alive
• RSET - unmarks all deletions
• QUIT - ends session, commits deletions

Optional Commands (RFC 1939)

• APOP - challenge-response authentication (MD5-based)
• TOP - retrieves headers and first N lines of body
• UIDL - returns unique identifiers for messages

Extensions

CAPA (RFC 2449)

The CAPA command allows clients to discover server capabilities. The server responds with a list of supported extensions:

C: CAPA
S: +OK Capability list follows
S: USER
S: STLS
S: UIDL
S: TOP
S: SASL PLAIN LOGIN CRAM-MD5 SCRAM-SHA-256
S: UTF8
S: PIPELINING
S: RESP-CODES
S: AUTH-RESP-CODE
S: EXPIRE NEVER
S: LOGIN-DELAY 5
S: IMPLEMENTATION gumdrop
S: .

STLS (RFC 2595)

Upgrades a cleartext connection to TLS. After successful STLS, the client should re-issue CAPA to discover post-TLS capabilities (authentication mechanisms may change).

C: STLS
S: +OK Begin TLS negotiation
(TLS handshake)
C: CAPA
...

AUTH (RFC 5034)

SASL authentication mechanism support. The server advertises available mechanisms in CAPA response. See Authentication for supported mechanisms.

UTF8 (RFC 6816)

Enables UTF-8 mode for international mailbox content. When enabled, message headers and bodies may contain UTF-8 encoded text.

C: UTF8
S: +OK UTF-8 mode enabled

PIPELINING (RFC 2449)

When enabled, clients can send multiple commands without waiting for responses. This reduces round-trip latency for batch operations.

RESP-CODES (RFC 2449 section 8)

The server includes extended response codes in -ERR replies to help clients provide meaningful error messages. Supported codes:

• [AUTH] — authentication failures (wrong password, bad credentials, unsupported mechanism)
• [SYS/TEMP] — temporary server errors (mailbox I/O, timeouts, connection issues)
• [SYS/PERM] — permanent configuration errors (auth or mailbox not configured)

AUTH-RESP-CODE (RFC 3206)

Extends RESP-CODES with authentication-specific [AUTH] response codes. All authentication failure -ERR replies include the [AUTH] code, allowing clients to distinguish credential errors from server-side failures.

EXPIRE (RFC 2449 section 6.5)

Declares the message retention policy. Configured via setExpireDays(int) on POP3Listener: 0 means messages may be expired immediately, a positive value is the minimum retention in days, and Integer.MAX_VALUE advertises EXPIRE NEVER. Set to -1 to suppress the capability.

LOGIN-DELAY (RFC 2449 section 6.6)

Advertises the minimum delay between authentication attempts. When loginDelayMs is greater than zero, the server advertises LOGIN-DELAY <seconds> so clients can avoid premature retries.

Authentication

Authentication uses Gumdrop's centralised Realm interface, shared with IMAP, SMTP, and other servers. Multiple authentication methods are supported.

Basic Authentication (USER/PASS)

The simplest method—client sends username and password in cleartext. Should only be used over TLS.

C: USER alice
S: +OK User accepted
C: PASS secret
S: +OK Mailbox locked and ready

APOP (RFC 1939)

Challenge-response authentication using MD5. The server includes a unique timestamp in its greeting; the client responds with MD5(timestamp + password). The password is never transmitted.

S: +OK POP3 server ready <1896.697170952@example.com>
C: APOP alice c4c9334bac560ecc979e58001b3e22fb
S: +OK Mailbox locked and ready

SASL Mechanisms

The AUTH command supports multiple SASL mechanisms:

SCRAM-SHA-256 is recommended as it provides mutual authentication and never transmits the password. The realm can store only derived keys without keeping plaintext passwords.

Authentication Example (SCRAM-SHA-256)

C: AUTH SCRAM-SHA-256
S: + (server first message, base64)
C: (client first message, base64)
S: + (server final message, base64)
C: (client final message, base64)
S: +OK Authentication successful

Mailbox Integration

The POP3 server accesses mail storage through the Mailbox API. A MailboxFactory provides MailboxStore instances for authenticated users.

Store Lifecycle

1. User authenticates successfully
2. Server calls mailboxFactory.createStore()
3. Store is opened with store.open(username)
4. Server opens the user's INBOX mailbox
5. Client retrieves messages, marks deletions
6. On QUIT, server calls mailbox.expunge() to commit deletions
7. Store is closed

Mailbox Locking

POP3 requires exclusive access to the mailbox during a session. The server acquires a lock when entering TRANSACTION state and releases it in UPDATE state. Concurrent POP3 connections to the same mailbox are rejected.

Message Identifiers

The UIDL command returns unique identifiers for each message. These identifiers are persistent across sessions, allowing clients to track which messages have been downloaded.

Configuration

POP3Listener Properties

org.bluezoo.gumdrop.pop3.POP3Listener (transport configuration):

• port - listening port (default: 110, or 995 for secure)
• secure - enable implicit TLS (POP3S)
• keystore-file - keystore for TLS/STLS
• keystore-pass - keystore password

DefaultPOP3Service Properties

org.bluezoo.gumdrop.pop3.DefaultPOP3Service (service logic):

• realm - reference to a Realm for authentication
• mailbox-factory - reference to a MailboxFactory
• enable-apop - enable APOP authentication (default: true)
• enable-utf8 - enable UTF-8 support (default: true)
• enable-pipelining - enable command pipelining (default: false)
• login-delay - delay after failed authentication in milliseconds (default: 0); helps mitigate brute-force attacks
• transaction-timeout - session timeout in milliseconds (default: 600000 / 10 minutes); RFC 1939 recommends at least 10 minutes
• expire-days - message retention policy advertised in CAPA: 0+ for days, Integer.MAX_VALUE for NEVER, -1 to suppress (default: -1)

Example Configuration

<!-- Authentication realm -->
<realm id="mailRealm" class="org.bluezoo.gumdrop.auth.BasicRealm">
    <property name="href">mail-users.xml</property>
</realm>

<!-- Mbox storage -->
<mailbox-factory id="mbox"
                 class="org.bluezoo.gumdrop.mailbox.mbox.MboxMailboxFactory">
    <property name="base-directory">/var/mail</property>
</mailbox-factory>

<!-- POP3 service (port 110 with STLS) -->
<service id="pop3" class="org.bluezoo.gumdrop.pop3.DefaultPOP3Service">
    <property name="realm" ref="#mailRealm"/>
    <property name="mailbox-factory" ref="#mbox"/>
    <property name="enable-apop">true</property>
    <property name="login-delay">3000</property>
    <listener class="org.bluezoo.gumdrop.pop3.POP3Listener">
        <property name="port">110</property>
        <property name="keystore-file">keystore.p12</property>
        <property name="keystore-pass">secret</property>
    </listener>
</service>

<!-- POP3S service (port 995 with implicit TLS) -->
<service id="pop3s" class="org.bluezoo.gumdrop.pop3.DefaultPOP3Service">
    <property name="realm" ref="#mailRealm"/>
    <property name="mailbox-factory" ref="#mbox"/>
    <listener class="org.bluezoo.gumdrop.pop3.POP3Listener">
        <property name="port">995</property>
        <property name="secure">true</property>
        <property name="keystore-file">keystore.p12</property>
        <property name="keystore-pass">secret</property>
    </listener>
</service>

Security

Transport Security

• POP3S (port 995) - implicit TLS; connection is encrypted from the start
• STLS (port 110) - upgrade cleartext connection to TLS

RFC 8314 recommends implicit TLS (port 995) over STLS for new deployments. STLS remains available for compatibility with older clients.

Credential Protection

• APOP - password never transmitted; MD5(timestamp + password)
• CRAM-MD5 - HMAC-MD5 challenge-response
• SCRAM-SHA-256 - mutual authentication with derived keys

USER/PASS and AUTH PLAIN transmit credentials in cleartext and should only be used over TLS. The server can be configured to reject these mechanisms without TLS.

Brute-Force Mitigation

The loginDelay setting introduces a delay after failed authentication attempts:

• Set to 3000 (3 seconds) to slow down automated attacks
• Applies per-connection; subsequent attempts within a session are delayed
• Does not affect successful authentications

Session Timeout

The transactionTimeout setting closes idle connections:

• Default 10 minutes per RFC 1939 recommendation
• Prevents resource exhaustion from abandoned connections
• Timer resets on each client command

Mailbox Locking

Exclusive mailbox access prevents data corruption from concurrent modifications. If a mailbox is already locked by another session, authentication fails with an appropriate error.

← Back to Main Page | IMAP Server | SMTP Server & Client | DNS Server | Telemetry

Gumdrop POP3 Server