AuthenticatingIMAPClient.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  18. package org.apache.commons.net.imap;

  20. import java.io.IOException;
  21. import java.security.InvalidKeyException;
  22. import java.security.NoSuchAlgorithmException;
  23. import java.security.spec.InvalidKeySpecException;
  24. import java.util.Base64;

  26. import javax.crypto.Mac;
  27. import javax.crypto.spec.SecretKeySpec;
  28. import javax.net.ssl.SSLContext;

  30. /**
  31.  * An IMAP Client class with authentication support.
  32.  *
  33.  * @see IMAPSClient
  34.  */
  35. public class AuthenticatingIMAPClient extends IMAPSClient {

  37.     /**
  38.      * The enumeration of currently-supported authentication methods.
  39.      */
  40.     public enum AUTH_METHOD {

  42.         /** The standardized (RFC4616) PLAIN method, which sends the password unencrypted (insecure). */

  44.         PLAIN("PLAIN"),
  45.         /** The standardized (RFC2195) CRAM-MD5 method, which doesn't send the password (secure). */

  47.         CRAM_MD5("CRAM-MD5"),

  49.         /** The standardized Microsoft LOGIN method, which sends the password unencrypted (insecure). */
  50.         LOGIN("LOGIN"),

  52.         /** XOAUTH */
  53.         XOAUTH("XOAUTH"),

  55.         /** XOAUTH 2 */
  56.         XOAUTH2("XOAUTH2");

  58.         private final String authName;

  60.         AUTH_METHOD(final String name) {
  61.             this.authName = name;
  62.         }

  64.         /**
  65.          * Gets the name of the given authentication method suitable for the server.
  66.          *
  67.          * @return The name of the given authentication method suitable for the server.
  68.          */
  69.         public final String getAuthName() {
  70.             return authName;
  71.         }
  72.     }

  74.     /** {@link Mac} algorithm. */
  75.     private static final String MAC_ALGORITHM = "HmacMD5";

  77.     /**
  78.      * Constructor for AuthenticatingIMAPClient that delegates to IMAPSClient. Sets security mode to explicit (isImplicit = false).
  79.      */
  80.     public AuthenticatingIMAPClient() {
  81.         this(DEFAULT_PROTOCOL, false);
  82.     }

  84.     /**
  85.      * Constructor for AuthenticatingIMAPClient that delegates to IMAPSClient.
  86.      *
  87.      * @param implicit The security mode (Implicit/Explicit).
  88.      */
  89.     public AuthenticatingIMAPClient(final boolean implicit) {
  90.         this(DEFAULT_PROTOCOL, implicit);
  91.     }

  93.     /**
  94.      * Constructor for AuthenticatingIMAPClient that delegates to IMAPSClient.
  95.      *
  96.      * @param implicit The security mode(Implicit/Explicit).
  97.      * @param ctx      A pre-configured SSL Context.
  98.      */
  99.     public AuthenticatingIMAPClient(final boolean implicit, final SSLContext ctx) {
  100.         this(DEFAULT_PROTOCOL, implicit, ctx);
  101.     }

  103.     /**
  104.      * Constructor for AuthenticatingIMAPClient that delegates to IMAPSClient.
  105.      *
  106.      * @param context A pre-configured SSL Context.
  107.      */
  108.     public AuthenticatingIMAPClient(final SSLContext context) {
  109.         this(false, context);
  110.     }

  112.     /**
  113.      * Constructor for AuthenticatingIMAPClient that delegates to IMAPSClient.
  114.      *
  115.      * @param proto the protocol.
  116.      */
  117.     public AuthenticatingIMAPClient(final String proto) {
  118.         this(proto, false);
  119.     }

  121.     /**
  122.      * Constructor for AuthenticatingIMAPClient that delegates to IMAPSClient.
  123.      *
  124.      * @param proto    the protocol.
  125.      * @param implicit The security mode(Implicit/Explicit).
  126.      */
  127.     public AuthenticatingIMAPClient(final String proto, final boolean implicit) {
  128.         this(proto, implicit, null);
  129.     }

  131.     /**
  132.      * Constructor for AuthenticatingIMAPClient that delegates to IMAPSClient.
  133.      *
  134.      * @param proto    the protocol.
  135.      * @param implicit The security mode(Implicit/Explicit).
  136.      * @param ctx      the context
  137.      */
  138.     public AuthenticatingIMAPClient(final String proto, final boolean implicit, final SSLContext ctx) {
  139.         super(proto, implicit, ctx);
  140.     }

  142.     /**
  143.      * Authenticate to the IMAP server by sending the AUTHENTICATE command with the selected mechanism, using the given user and the given password.
  144.      *
  145.      * @param method   the method name
  146.      * @param user user
  147.      * @param password password
  148.      * @return True if successfully completed, false if not.
  149.      * @throws IOException              If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  150.      * @throws NoSuchAlgorithmException If the CRAM hash algorithm cannot be instantiated by the Java runtime system.
  151.      * @throws InvalidKeyException      If the CRAM hash algorithm failed to use the given password.
  152.      * @throws InvalidKeySpecException  If the CRAM hash algorithm failed to use the given password.
  153.      */
  154.     public boolean auth(final AuthenticatingIMAPClient.AUTH_METHOD method, final String user, final String password)
  155.             throws IOException, NoSuchAlgorithmException, InvalidKeyException, InvalidKeySpecException {
  156.         if (!IMAPReply.isContinuation(sendCommand(IMAPCommand.AUTHENTICATE, method.getAuthName()))) {
  157.             return false;
  158.         }

  160.         switch (method) {
  161.         case PLAIN: {
  162.             // the server sends an empty response ("+ "), so we don't have to read it.
  163.             final int result = sendData(Base64.getEncoder().encodeToString(("\000" + user + "\000" + password).getBytes(getCharset())));
  164.             if (result == IMAPReply.OK) {
  165.                 setState(IMAP.IMAPState.AUTH_STATE);
  166.             }
  167.             return result == IMAPReply.OK;
  168.         }
  169.         case CRAM_MD5: {
  170.             // get the CRAM challenge (after "+ ")
  171.             final byte[] serverChallenge = Base64.getDecoder().decode(getReplyString().substring(2).trim());
  172.             // get the Mac instance
  173.             final Mac hmacMd5 = Mac.getInstance(MAC_ALGORITHM);
  174.             hmacMd5.init(new SecretKeySpec(password.getBytes(getCharset()), MAC_ALGORITHM));
  175.             // compute the result:
  176.             final byte[] hmacResult = convertToHexString(hmacMd5.doFinal(serverChallenge)).getBytes(getCharset());
  177.             // join the byte arrays to form the reply
  178.             final byte[] usernameBytes = user.getBytes(getCharset());
  179.             final byte[] toEncode = new byte[usernameBytes.length + 1 /* the space */ + hmacResult.length];
  180.             System.arraycopy(usernameBytes, 0, toEncode, 0, usernameBytes.length);
  181.             toEncode[usernameBytes.length] = ' ';
  182.             System.arraycopy(hmacResult, 0, toEncode, usernameBytes.length + 1, hmacResult.length);
  183.             // send the reply and read the server code:
  184.             final int result = sendData(Base64.getEncoder().encodeToString(toEncode));
  185.             if (result == IMAPReply.OK) {
  186.                 setState(IMAP.IMAPState.AUTH_STATE);
  187.             }
  188.             return result == IMAPReply.OK;
  189.         }
  190.         case LOGIN: {
  191.             // the server sends fixed responses (base64("UserName") and
  192.             // base64("Password")), so we don't have to read them.
  193.             if (sendData(Base64.getEncoder().encodeToString(user.getBytes(getCharset()))) != IMAPReply.CONT) {
  194.                 return false;
  195.             }
  196.             final int result = sendData(Base64.getEncoder().encodeToString(password.getBytes(getCharset())));
  197.             if (result == IMAPReply.OK) {
  198.                 setState(IMAP.IMAPState.AUTH_STATE);
  199.             }
  200.             return result == IMAPReply.OK;
  201.         }
  202.         case XOAUTH:
  203.         case XOAUTH2: {
  204.             final int result = sendData(user);
  205.             if (result == IMAPReply.OK) {
  206.                 setState(IMAP.IMAPState.AUTH_STATE);
  207.             }
  208.             return result == IMAPReply.OK;
  209.         }
  210.         }
  211.         return false; // safety check
  212.     }

  214.     /**
  215.      * Authenticate to the IMAP server by sending the AUTHENTICATE command with the selected mechanism, using the given user and the given password.
  216.      *
  217.      * @param method   the method name
  218.      * @param user user
  219.      * @param password password
  220.      * @return True if successfully completed, false if not.
  221.      * @throws IOException              If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  222.      * @throws NoSuchAlgorithmException If the CRAM hash algorithm cannot be instantiated by the Java runtime system.
  223.      * @throws InvalidKeyException      If the CRAM hash algorithm failed to use the given password.
  224.      * @throws InvalidKeySpecException  If the CRAM hash algorithm failed to use the given password.
  225.      */
  226.     public boolean authenticate(final AuthenticatingIMAPClient.AUTH_METHOD method, final String user, final String password)
  227.             throws IOException, NoSuchAlgorithmException, InvalidKeyException, InvalidKeySpecException {
  228.         return auth(method, user, password);
  229.     }

  231.     /**
  232.      * Converts the given byte array to a String containing the hexadecimal values of the bytes. For example, the byte 'A' will be converted to '41', because
  233.      * this is the ASCII code (and the byte value) of the capital letter 'A'.
  234.      *
  235.      * @param a The byte array to convert.
  236.      * @return The resulting String of hexadecimal codes.
  237.      */
  238.     private String convertToHexString(final byte[] a) {
  239.         final StringBuilder result = new StringBuilder(a.length * 2);
  240.         for (final byte element : a) {
  241.             if ((element & 0x0FF) <= 15) {
  242.                 result.append("0");
  243.             }
  244.             result.append(Integer.toHexString(element & 0x0FF));
  245.         }
  246.         return result.toString();
  247.     }
  248. }
Created with JaCoCo 0.8.12.202403310830