Binc IMAP - FAQ GNU General Public License
Andreas Aardal Hanssen <andreas@hanssen.name>
Q: Why did you start writing Binc IMAP?

First of all, I work a lot with qmail servers, and there haven't really been many Maildir capable IMAP4rev1 servers around. I used Courier-IMAP for years, but after loads of abuse from the Courier community and its author, I found that earth had room for one more IMAP4rev1 server.

Enjoying the simplicity of qmail-pop3d, I decided to create an IMAP server that was equally simple to install and use, and that could work side-by-side with qmail-pop3d to provide IMAP service to qmail users.

I had already written an IMAP server for proxying POP3-accounts at work, and I had so many good experiences from that project that I beleived that I could really write a great IMAP server.

Well, it's up to you to determine how great it is, but I swear it has it's advantages over the existing Maildir capable IMAP servers out there.

Q: What is "Binc"?

This should be quite obvious: Binc Is Not Courier-IMAP :-).

Q: Why should I use Binc IMAP, and not the other Maildir capable IMAP servers?

Binc IMAP is a light weight alternative to existing IMAP servers. It's easier to install, easier to maintain, and it's easy to integrate into existing (perhaps legacy) authentication environments.

Binc IMAP is small and simple. The total number of lines of source code is much smaller in Binc than in the other servers. Version 1.0.24-1 of Binc IMAP has about 18000 lines of code. There are only 17000 lines of hand written code, including comments. Few lines in itself does not imply that the code is better, but it's certainly much easier to maintain.

It is also written in C++, using standard C++ data components. If this server crashes, it'll most likely abort, and not suffer a segmentation fault, which is the most common reason for exploits.

It was designed before written(*), using an object oriented design all the way. A modular, simple design with few lines of code means that it's easier to uncover bugs, and it's easier to fix them without disturbing the rest of the source code.

This is free software, and you are free to choose the IMAP server that suits your needs the best. Here are some of Binc IMAP's fellow Maildir capable IMAP servers:

  • Courier-IMAP
    • Programming language is C
    • Supports many extensions
    • Only supports Maildir
    • Is not compliant with the IMAP4rev1 protocol as defined in RFC2060, and it's author has no plans on making it compliant. I have had several complaints to the Courier community, among others that sequence sets are not interpreted correctly. Search on Google Groups for "courier imap +compliant Mark Crispin" for more info on Courier's disregards for Internet standards.
    • The community is in general hostile and not open for input.
    • It uses its own homebrew TCP wrapper. Modern TCP wrappers are advanced enough to do a better job.
    • Courier-IMAP v1.6.2.20030119 consisted of over 80000 lines of C code. That's less than UW-IMAP's 125000 lines, but it's still very much code.
    • One thing that Courier-IMAP has done right for the IMAP world is to provoke other open source authors to write better servers. :-)
  • Dovecot IMAP
    • Programming language is C
    • Supports Maildir and mbox
    • Uses indexes to speed up mailbox access.
    • Has race conditions where mails can disappear.
    • Focuses on security, with among others, privilege seperation. Change logs show a history of mailbox curruption. I can't confirm how big this problem is.
    • Uses its own homebrew TCP wrapper.
    • Approx. 50000 lines of code in v0.99.7.

For comparison, here are some key points about Binc IMAP:

  • Programming language is C++
  • Only supports Maildir
  • The main goal is to provide a compliant IMAP server that works.
  • Focuses on portability, easy install, easy server maintenance, easy source code maintenance & build. Over time, this will prove to be the clue to providing a secure service.
  • Uses xinetd or tcpserver, or similar TCP wrappers. I beleive that developers who write good TCP wrappers should focus on that, and those who write good IMAP servers should not waste time debugging code that is not relevant to the project.
  • Binc has approximately 18000 lines of code in v1.0.24.
Q: So Binc IMAP doesn't focus on security?
  • Security comes naturally with a service with a clean, correct design and no bugs
  • Security can not be claimed. To prove that a server is not secure, one must simply find a way to exploit it. Claiming that a server is secure is like claiming that nobody can find a way to break it.
  • The only true argument is to prove that it's secure. And that's almost impossible.
  • Binc IMAP focuses on creating a service with a clean, correct design with no bugs. Time and experience will tell wether it's a secure server or not.
Q: Is Binc IMAP fast?

Binc IMAP focuses its optimizations on the type of activity that dominates the lifetime of an IMAP connection, which is idle time.

  • Pending updates: When a client issues NOOP, CHECK or similar, the server must give the latest changes to the depository. If no changes have been made, this operation will with Binc IMAP consist of only two stat-calls, which is extremely fast.
  • FETCH: Multiple subsequent operations on the same message will never cause the message to be parsed more than twice - once for header-only operations and once for full message info.
  • STATUS: The status command is typically used to check for new messages in all subscribed mailboxes. If no changes have been made to a mailbox, the status command in Binc IMAP consists of only two stat calls, which is extremely fast.
  • SEARCH: The search keys are weighted, and the search query is sorted with lightest-search first. This prevents unnecessary processing of slow search keys if the light search keys do not match the message set.

Some activity is not optimal in Binc IMAP, and searching for random text in particular is no faster than a sequential search using standard UNIX tools such as grep. Searching for text in a large mailbox is quite rare, however, compared to the random activity of close-to-idle clients.

Q: Is Binc IMAP a stable, secure server?

It's hard to write bug free programs, especially with a complex protocol like IMAP4rev1. Any attempts to verify code usually comes down to the limitations in the author's experience with verification. Or as Donald Knuth said (my favorite quote):

"Beware of bugs in the above code; I have only proved it correct, not tried it."

Knuth teaches that it can be easy to prove that your code is correct, but who's going to prove that your proof is correct? Proving your proof might turn out to be close to impossle. What you can have, is conventions and principles that prevent bugs from showing up in your programs. Here are mine:

  • Don't reinvent the wheel. Unless absolutely necessary, write code that doesn't exist already.
  • Spend your time on making it work as simple as possible, then start making optimizations.
  • Don't let optimization obfuscate your source code.
  • Find a better algorithm, or if you can't get the speed that you want, change to a more efficient programming language.
  • Handle all error conditions.
  • Avoid buffers altogether.
  • Don't hand write parsers unless strictly necessary - they are hard to get right.
  • For G's sake, be compliant! If the standard has flaws, then help fix the flaws - don't break the standard.

Now I don't pay $2.56^n where n equals the total number of bugs discovered in Binc IMAP, but I will certainly give you many pats on the back if I get the chance. :-)

I could go on and on, but the point is that I have tried my best to perform all the expected tasks in the most logical and obvious way possible, using all my C++ security experience to aid me. But at the time of writing, the server is young, the community small, and we are only in Beta. So time will have to tell how stable and secure we are.

Q: Which configuration files are used by Binc IMAP?
  • /etc/opt/bincimap/supervise/imap/run
  • /etc/opt/bincimap/supervise/imaps/run
  • /etc/opt/bincimap/xinetd/imap
  • /etc/opt/bincimap/xinetd/imaps

These files are for administrators. You can set up Binc IMAP's authentication method here.

  • /etc/opt/bincimap/bincimap.conf

This first file is for setting global administrator settings, such as paths to the host's SSL certificate, timeouts for idle clients and so on. It need not be readable for anyone but root.

  • $HOME/.bincimap

This file is for individual settings, such as what the exact path is to this user's Maildir (for instance, /var/mail/$USER/Maildir). It is currently not used for much.

Q: How can I tell Binc IMAP where my Maildirs are?

The configuration file has a section called Mailbox. You can set the path to your users' Maildir there, relative to the users' home areas.

If your Maildirs are not is users' homeareas, for instance if your Maildir depository has a /var/mail/user/ structure, you can safely set path to "". Your authenticator must then return the full path of the Maildir.

Q: How can I get SSL to work?

SSL in Binc IMAP is quite simple to set up. First you need a PEM encoded certificate file. In some distributions, you can generate this file by changing to /usr/share/ssl/certs and running "make". A script will give you the option to build a PEM file.

When you have a PEM file, edit bincimap.conf in the SSL section . You need to add an item called pem file and set it to point to your PEM certificate. The path name must be absolute. For example:

  SSL {
    pem file = "/usr/share/ssl/certs/mypemfile.pem",
    ca file = "",
    cipher list = "!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP",
    verify peer = "yes"
  }

The item ca file in bincimap.conf tells Binc IMAP which file on your system contains a bundle of certificate authorities.

Next comes the item called cipher list. It tells Binc IMAP about which ciphers you want your server to support. This depends on what version of OpenSSL you're running.

Last comes an option called verify peer. This tells Binc IMAP to attempt to verify the client's identity.

Visit this link at the Apache.org website to read more about SSL and TLS principles.

Q: How do I find my folders in Binc IMAP?

All folders in Binc IMAP must be subfolders of INBOX.

This means that if you want to create a folder called work, you have to create INBOX.work or INBOX/work.

For some graphical IMAP clients like Outlook (look out!) or Mozilla Mail, this means you need to right click on INBOX and select "Create subfolder".

Note: Remember to subscribe to your folders.

Q: How does Binc IMAP authentication work?

Binc IMAP is spawned by xinetd, tcpserver or any other TCP wrapper running as root.

It immediately goes into pre-authentication mode, where it expects the client to enter STARTTLS if the client is not already running an SSL connection. When in TLS/SSL mode, it will accept clear text authentication.

Binc IMAP uses a generic authentication method which currently only has support for checkpassword. Binc invokes a checkpassword stub called bincimap-auth-checkpassword, and sends the username and password in two environment variables.

The checkpassword stub then forks and the child invokes its first argument, which typically is /bin/checkpassword. The stub then writes the username and password to fd 3. checkpassword accepts the password, and invokes its first argument directly, replacing the checkpassword process itself.

The program invoked by checkpassword is bincimap-uidpwd. Its sole purpose is to write the user id, the group id and the user's home directory to stdout in the following format:

uid.gid\n
pwd\n

or

500.500\n
/home/user\n

The uidpwd process then exits, and is caught by the authentication stub, bincimap-auth-checkpassword. The stub analyzes the exit code of its child, and reads the child's stdout output if the exit code indicates that authentication succeeded. It writes the data it read from the child to its own stdout.

If authentication succeeded, the stub exits with exitcode 0. If authentication failed, it exits 100. If there was an internal error with authenticating the user, it exits 111.

Binc then catches its stub and checks its exit code, and reads data from the stub's stdout if authentication succeeded.

At the final stage, Binc IMAP can chroot to the user's home directory + "/Maildir" and setuid/setgid to operate under this user's priviledges.

Q: How can I write my own Binc IMAP authenticator?

You can write your own authenticator in Perl, Python, bash, C++, Java or whichever language you like. And it's easy.

  • 1.0.24 and older: Write a standalone executable that reads the username and password from the environment. Note that there are security issues with using this method on some platforms.The environment variables are: 
    BINC_USERID
BINC_PASSWD
  • From 1.0.25 and on: Read the user ID and password from stdin in netstring format. The first string is the user ID and the second is the password, as in the following example (note the trailing comma, and there is no line feed): 
    7:andreas,8:mysecret,
  • Make the stub do your piece of magic: figure out wether the password is correct or not, and find the user's home directory. Write these to stdout if authentication was successful, in the format described in the former question.
  • Edit your xinetd or supervise "run" files so that your stub is called as the first non-option argument after bincimapd, as in the following example: 
    /opt/bincimap/bin/bincimapd                \
   --conf=/etc/opt/bincimap/bincimap.conf  \
   --ssl                                   \
/usr/local/bin/myauthenticator
Q: How do I fix this: "Unable to find required function getopt_long"?

The getopt_long function is a GNU extension to the POSIX.2 getopt function. It allows long arguments such as --enable-ssl.

Unfortunately, this function is not defined on all platforms. Specifically, it is known to not exist on FreeBSD.

For FreeBSD users, install gnugetopt from ports. Otherwise, post this problem with as much relevant info as you can provide, to the mailing list.

Q: How do I fix this: "Unable to find the crypto library which is part of OpenSSL"?

The crypto library is a part of OpenSSL. This library is required for Binc IMAP to compile.

If you can not get Binc IMAP to compile with OpenSSL, there should be a static RPM package available for download.

Q: How do I fix this: "Unable to find the ssl library which is part of OpenSSL"?

The crypto library is a part of OpenSSL. This library is required for Binc IMAP to compile.

If you can not get Binc IMAP to compile with OpenSSL, there should be a static RPM package available for download.

Q: How do I install Binc IMAP?

The easiest way to install Binc IMAP on your server is to follow these instructions:

  • Download the RPM from http://www.bincimap.andreas.hanssen.name/dl/RPMS
  • Install the RPM
  • Copy, edit and perhaps symlink the configuration files:
    • with daemontools:
      • ln -s /etc/opt/bincimap/supervise/imap /service/imap
      • ln -s /etc/opt/bincimap/supervise/imaps /service/imaps
    • with xinetd:
      • ln -s /etc/opt/bincimap/xinetd/imap /etc/xinetd.d/imap
      • ln -s /etc/opt/bincimap/xinetd/imaps /etc/xinetd.d/imaps
      • service xinetd restart
  • Check that the service is up by connecting using a standard IMAP client

If you want to build Binc IMAP from source, there's a README file that gives you the instructions step by step, inside the tarball. You can also get some clues by inspecting the bundled bincimap-spec file's install section.

Q: Why does Binc IMAP (RPM) install under /opt?

The reason for this is that I have tried my best to follow the File System Hierarchy Standard.

Binaries go under /opt/bincimap/bin

Host specific configuration goes under /etc/opt/bincimap

If you want your files elsewhere, there's always the option to build the project from source. :-)

(*) Binc IMAP was designed before implementation started. However, the current implementation deviates from the original design to some extent. The design is likely to be revised some time in near future.
Valid HTML 4.01! Powered by djbdns! Powered by Binc IMAP