Mail Auth Utils

This is a collection of Python scripts for generating login/authentication strings for SMTP, IMAP, and ManageSieve servers. These scripts are useful if you’re trying to debug an auth problem with one of these servers, and want to login manually using a telnet-like program like gnutls-cli or openssl s_client rather than using a full mail client. They are also generally useful if you’re trying to understand the basics of how these protocols work under the hood.

So far only RFC 4616 PLAIN SASL authentication has been implemented. This should work for the nearly all real-world mail servers that secure connections using STARTTLS (or native TLS). Enhancements to support other authentication schemes (e.g. CRAM-MD5 and DIGEST-MD5) are welcome!

This code is free software, licensed under the GPLv3, or (at your option) any later version.

Installation

Install from PyPI:

$ pip install mail-auth-utils

Or use the setup.py as you would for any other Python project:

$ python setup.py install

Usage

All of the commands all of the commands will accept a positional username, and optionally a password using -p or --password. If no username is provided, a default will be guessed based on the environment; this probably isn’t correct unless you’re using local mail delivery, so be sure to specify a username! If no password is supplied you will be prompted for secure password entry on stdin.

The commands will all print the protocol string used to authenticate, which may be multiple lines if the authentication protocol requires interaction with the server. If this sounds confusing, the exact usage should be clear from the examples below. All of the protocol examples use gnutls-cli for interaction with the remote server. Strings sent by the server are prefixed with S: and strings sent by the client (i.e. you) are prefixed with C:, which is the same convention used in the IETF mail RFCs.

SMTP AUTH

Generate an AUTH PLAIN login command using smtp-auth:

$ smtp-auth -p testpass testuser
AUTH PLAIN AHRlc3R1c2VyAHRlc3RwYXNz

You can also use the --auth-login option to generate a legacy AUTH LOGIN command instead of AUTH PLAIN.

The protocol should look something like this with an SMTP server that uses STARTTLS:

$ gnutls-cli -s -p 25 smtp.mydomain.com
S: 220 smtp.mydomain.com ESMTP Postfix Ready
C: EHLO smtp.mydomain.com
S: ...
C: STARTTLS
S: 220 2.0.0 Ready to start TLS
<type Ctrl-D in gnutls-cli>
C: AUTH PLAIN AHRlc3R1c2VyAHRlc3RwYXNz
S: 235 2.0.0 OK Authenticated

IMAP PLAIN Authentication

Generate a base64 encoded username and password using imap-auth. The command will print an IMAP authenticate protocol message followed by the encoded username and password:

$ imap-auth -p testpass testuser
1 AUTHENTICATE PLAIN
dGVzdHVzZXIAdGVzdHVzZXIAdGVzdHBhc3M=

The protocol should look something like this using with an IMAP server using IMAPS on port 993 (note that this is not STARTTLS, as IMAP generally uses native TLS on this port):

$ gnutls-cli -p 993 imap.mydomain.com
S: * OK [CAPABILITY IMAP4rev1 ...] Dovecot ready.
C: 1 AUTHENTICATE PLAIN
S: +
C: dGVzdHVzZXIAdGVzdHVzZXIAdGVzdHBhc3M=
S: 1 OK [CAPABILITY IMAP4rev1 ....] Logged in

ManageSieve PLAIN Authentication

Generate a base64 encoded username and password using sieve-auth (typically this would be the same username and password you use for IMAP):

$ sieve-auth -p testpass testuser
AUTHENTICATE "PLAIN" "AHRlc3R1c2VyAHRlc3RwYXNz"

The protocol should look something like this for a remote ManageSieve server that uses STARTTLS:

$ gnutls-cli -s -p 4190 imap.mydomain.com
S: "IMPLEMENTATION" "Dovecot Pigeonhole"
   ...
   OK "Dovecot ready."
C: STARTTLS
S: OK "Begin TLS negotiation now."
<type Ctrl-D in gnutls-cli>
S: OK "TLS negotiation successful."
C: AUTHENTICATE "PLAIN" "AHRlc3R1c2VyAHRlc3RwYXNz"
S: OK "Logged in."