How to configure APOP for JBoss Mail Server 1.0-M5

versions: 1.0M5-pre1

Overview

APOP is a way to prevent replay attacks over encrypted or unencrypted POP3 streams.  APOP is most useful for unencrypted POP3 streams as TLS/SSL also incorporates protection for replay attacks.  You can find an explanation on the Wikipedia APOP topic.  Mozilla's Thunderbird, for example, supports APOP but calls it "Secure Authentication" (other clients support it as well).

Allow non-APOP authentication

You may choose to allow both APOP and standard USER/PASS authentication (especially if POP3SSL is enabled).  If you are going to do this you should supply both APOP and NON-APOP user repository instances.  If you wish to ONLY allow APOP then supply only an APOP-based JAAS login module and user repository.  If you allow SMTP authentication you'll probably need to keep the non-APOP based JAAS login modules in addition to the APOP-based login modules. 

Configuring a login module for APOP

Edit the $JBMS_HOME/server/$CONFIG/deploy/jboss-service.xml.  Uncomment the a security config called "jboss-mail-apop".  Find the following:

   <!-- UserRepository implementation for JAAS
                Uncomment and comment StaticUserRepository above to enable
                A JAAS security domain must be configured in conf/login-config.xml
                Currently only authenticates a user, no roles are checked

  <mbean code="org.jboss.mail.userrepository.jaas.JaasUserRepository"
    name="jboss.mail:type=MailServices,name=UserRepository,uimanageable=true,apop=true">
    <depends>jboss.security:service=JaasSecurityManager</depends>
        <attribute name="SecurityDomain">jboss-mail-apop</attribute>
  </mbean -->

Uncomment it so that it looks like this:

   <!-- UserRepository implementation for JAAS
                Uncomment and comment StaticUserRepository above to enable
                A JAAS security domain must be configured in conf/login-config.xml
                Currently only authenticates a user, no roles are checked
  -->
  <mbean code="org.jboss.mail.userrepository.jaas.JaasUserRepository"
    name="jboss.mail:type=MailServices,name=UserRepository,uimanageable=true,apop=true">
    <depends>jboss.security:service=JaasSecurityManager</depends>
        <attribute name="SecurityDomain">jboss-mail-apop</attribute>
  </mbean>

Add an XML Block like this:

   <mbean code="org.jboss.security.auth.login.DynamicLoginConfig"
      name="jboss.mail:type=SecurityConfig,name=LoginConfigAPOP">
      <attribute name="PolicyConfig" serialDataType="jbxb">
         <jaas:policy
            xsi:schemaLocation="urn:jboss:security-config:4.1 resource:security-config_4_1.xsd"
            xmlns:jaas="urn:jboss:security-config:4.1"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            >
            <jaas:application-policy name="jboss-mail-apop">
               <jaas:authentication>
                  <jaas:login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
                     flag="required">
                         <jaas:module-option name="usersProperties">jbms-users.properties</jaas:module-option>
                         <jaas:module-option name="rolesProperties">jbms-roles.properties</jaas:module-option>
                         <jaas:module-option name="callback.option.serviceName">jboss.mail:type=MailServices,name=UserRepository,uimanageable=true,apop=true</module-option>
                         <jaas:module-option name="storeDigestCallback">org.jboss.mail.userrepository.jaas.ApopDigestCallback</module-option>
                         <jaas:module-option name="hashStorePassword">true</module-option>
                         <jaas:module-option name="hashAlgorithm">MD5</module-option>
                         <jaas:module-option name="hashEncoding">HEX</module-option>
                         <jaas:module-option name="unauthenticatedIdentity">nobody</jaas:module-option>
                  </jaas:login-module>
               </jaas:authentication>
            </jaas:application-policy>
         </jaas:policy>
      </attribute>
      <depends optional-attribute-name="LoginConfigService">
         jboss.security:service=XMLLoginConfig
      </depends>
      <depends optional-attribute-name="SecurityManagerService">
         jboss.security:service=JaasSecurityManager
      </depends>
   </mbean>

Find your POP3 configuration line that reads as follows:

        <!--depends optional-attribute-name="APOPUserRepository"
                         proxy-type="attribute">jboss.mail:type=MailServices,name=UserRepository,uimanageable=true,apop=true</depends-->

Configuring POP to use the APOP User Repository

Locate the POPProtocol in the jboss-service.xml and edit it as follows:

  <mbean code="org.jboss.mail.pop3.POP3Protocol"
    name="jboss.mail:type=MailServices,name=POP3Protocol">
...
        <depends optional-attribute-name="UserRepository"
                         proxy-type="attribute">jboss.mail:type=MailServices,name=UserRepository,uimanageable=true</depends>
        <depends optional-attribute-name="APOPUserRepository"                            
            proxy-type="attribute">jboss.mail:type=MailServices,name=UserRepository,uimanageable=true,apop=true</depends>

Add the APOPUserRepository attribute as above.  If you are NOT going to allow non-APOP authentication then remove the UserRepository entry. 

POPSSL

If you have POP/SSL enabled you can also add the APOPUserRepository entry to it. 

What this does

In the first step you configured (uncommented) the JAASUserRepository to point to the APOP login module.  In the second step you configured a JAAS login module with APOP hashing enabled to check the user's password.  In the final step you configured the POP protocol to use the APOP-enabled JAASUserRepository for APOP authentication.  Alternatively, you may have left the non APOP-enabled UserRepository for non-APOP (USER/PASS) authentication.

Don't Panic

Just enable SSL/TLS and ignore all of this crap.  SSL/TLS is MORE secure than APOP and APOP is redundant of the security features of SSL/TLS.  Most mail clients at least support POP/SSL so this is mostly a checkbox feature.  In a future release we'll have support for configuring this in the automated graphical install.  What you DON'T want is to pass passwords in the clear (so require TLS authentication for POP and supply POP/SSL for mail clients that do not support TLS).