How to configure APOP for JBoss Mail Server 1.0-M4

versions: 1.0M4

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).

Configuring JAAS

In order to configure APOP on JBMS, you must use JAAS login modules.  See the "[HowToConfigureJAASIntegrationForJBossMailServer1.0M4|DOC-9924]" topic for basic JAAS configuration.  Enable the module of your choice.

Alow 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/conf/login-config.xml as you did for JAAS configuration.  Create a security domain called "jboss-mail-apop".  Add the "callback.option.serviceName" as below with your UserRepository's MBean name (see JAAS topic).  Also add the storeDigestCallback, hashStorePassword, hashAlgorithm and hashEncoding options exactly as below.

    <application-policy name = "jboss-mail-apop">
       <authentication>
          <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
             flag = "required"> 
           <module-option name="usersProperties">props/jmx-console-users.properties</module-option>
           <module-option name="rolesProperties">props/jmx-console-roles.properties</module-option>
           <module-option name="callback.option.serviceName">jboss.mail:type=MailServices,name=UserRepository,uimanageable=true</module-option>
           <module-option name="storeDigestCallback">org.jboss.mail.userrepository.jaas.ApopDigestCallback</module-option>
           <module-option name="hashStorePassword">true</module-option>
           <module-option name="hashAlgorithm">MD5</module-option>
           <module-option name="hashEncoding">HEX</module-option>
          </login-module>
       </authentication>
    </application-policy>

Optionally you may also include a non-apop instance of the same login module as below:

    <application-policy name = "jboss-mail">
       <authentication>
          <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
             flag = "required">
           <module-option name="usersProperties">props/jmx-console-users.properties</module-option>
           <module-option name="rolesProperties">props/jmx-console-roles.properties</module-option>
          </login-module>
       </authentication>
    </application-policy>      

It is not important whether you use the DB, LDAP, or some other login module, only the additional properties are important.

Configuring the UserRepository

Edit your $JBMS_HOME/server/$CONFIG/deploy/mail.ear/mail.sar/META-INF/jboss-service.xml.  Create a copy of the JAAS User Repository (see JAAS config topic) like below:

   <!-- 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">
...
        <attribute name="SecurityDomain">jboss-mail-apop</attribute>
  </mbean>

Make sure it references your jboss-mail-apop domain.  If you are going to allow both APOP and non-APOP user authentication then maintain a copy exactly as in the JAAS config topic.

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 a JAAS login module with APOP hashing enabled to check the user's password.  In the second step you configured the JAASUserRepository to point to that login module.  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).