.TH s/qmail: qmail-popup 8
.SH NAME
qmail-popup \- read a POP username and password
.SH SYNOPSIS
.B qmail-popup
.I hostname
.I subprogram
.SH DESCRIPTION
.B qmail-popup
reads a POP username and password from the network.
It then runs
.IR subprogram .

.B qmail-popup
expects descriptor 0 to read from the network
and descriptor 1 to write to the network.
It reads a username and password from descriptor 0
in POP's USER-PASS style or APOP style.
File descriptor 5 is used to provide additional logging.
It invokes
.IR subprogram ,
with the same descriptors 0 and 1;
descriptor 2 writing to the network;
and descriptor 3 reading the username, a 0 byte, the password,
another 0 byte, 
an APOP timestamp derived from
.IR hostname ,
and a final 0 byte.
.B qmail-popup
then waits for
.I subprogram
to finish.
It prints an error message if
.I subprogram
crashes or exits nonzero.

.B qmail-popup
has a 20-minute idle timeout.

.SH "AUTHENTICATION"
.B qmail-popup
supports both username/password and APOP authentication.
This latter is invoked, once the 
environment variable
.I POP3AUTH='apop'
or 
.I POP3AUTH='+apop'
is set. 
In this case, you need to provide a
APOP-capable PAM, eg. 
.BR qmail-authuser .

.B qmail-popup
should be used only within a secure network.
Otherwise an eavesdropper can steal passwords.
Even if you use APOP,
an active attacker can still take over the connection
and wreak havoc.

.SH "STLS/POP3S SUPPORT"
.B qmail-popup
can be adviced to work on a TLS encrypted connection.

At first, using
.B sslserver
and binding 
.BR qmail-popup ,
.B qmail-pop3d 
on (in particular) the POP3S port
.I 995 
provides mandatory TLS encryption.

Second, in case you provide
the environment variable 
.I UCSPITLS='' 
together with
.BR sslserver ,
.B qmail-popup
communicates with the
.B sslserver
program interface through a control socket, 
a reading and a writing pipe created dynamically
during the session start after announcing 
.I STLS
to the client, thus allowing TLS encryption on request.
In case
.IR UCSPITLS='!'
is set, STLS is required; while setting
.IR UCSPITLS='-'
disables STLS.

.SH "LOGGING"
.B qmail-popup
provides logging of accepted and rejected POP3 sessions
using about the same format as
.BR qmail-smtpd .
The authentication mechanism is indicated via
.I User 
in case the userid/password method was used, and
.I Apop
if APOP challenge/response was applicable.
The communication protocol may be either
.I POP3
or 
.I POP3S
for of a STLS/POP3S secured connection.
The
.I username
provided for authentication is displayed after the 
sequence 
.IR '?~' .
In case
.B qmail-popup
is setup requiring STLS by means of
.IR UCSPITLS='!' ,
the log displays 'Any' as auth method 
and 'unknown' as username.


The log is available on file descriptor 5. 
In order to display the result use the redirection '5>&1'.

.B qmail-popup
is based on a program contributed by Russ Nelson.

.SH "SEE ALSO"
maildir(5),
qmail-authuser(8),
qmail-pop3d(8),
qmail-log(8).