KMS: Support for multiple Kerberos principals. (tucu)

(cherry picked from commit fad4cd85b313a1d2378adcf03cad67e946a12cd5)

hadoop-common-project/hadoop-common/CHANGES.txt

@@ -499,6 +499,8 @@ Release 2.6.0 - UNRELEASED
     HADOOP-11105. MetricsSystemImpl could leak memory in registered callbacks.
     (Chuan Liu via cnauroth)
 
+    KMS: Support for multiple Kerberos principals. (tucu)
+
 Release 2.5.1 - 2014-09-05
 
   INCOMPATIBLE CHANGES

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/crypto/key/kms/KMSClientProvider.java

@@ -45,6 +45,7 @@ import java.io.InputStream;
 import java.io.OutputStream;
 import java.io.OutputStreamWriter;
 import java.io.Writer;
+import java.lang.reflect.UndeclaredThrowableException;
 import java.net.HttpURLConnection;
 import java.net.SocketTimeoutException;
 import java.net.URI;
@@ -400,6 +401,8 @@ public class KMSClientProvider extends KeyProvider implements CryptoExtension,
       });
     } catch (IOException ex) {
       throw ex;
+    } catch (UndeclaredThrowableException ex) {
+      throw new IOException(ex.getUndeclaredThrowable());
     } catch (Exception ex) {
       throw new IOException(ex);
     }

hadoop-common-project/hadoop-kms/src/site/apt/index.apt.vm

@@ -602,7 +602,31 @@ $ keytool -genkey -alias tomcat -keyalg RSA
 
 *** HTTP Kerberos Principals Configuration
 
-  TBD
+  When KMS instances are behind a load-balancer or VIP, clients will use the
+  hostname of the VIP. For Kerberos SPNEGO authentication, the hostname of the
+  URL is used to construct the Kerberos service name of the server,
+  <<<HTTP/#HOSTNAME#>>>. This means that all KMS instances must have a Kerberos
+  service name with the load-balancer or VIP hostname.
+
+  In order to be able to access directly a specific KMS instance, the KMS
+  instance must also have Keberos service name with its own hostname. This is
+  required for monitoring and admin purposes.
+
+  Both Kerberos service principal credentials (for the load-balancer/VIP
+  hostname and for the actual KMS instance hostname) must be in the keytab file
+  configured for authentication. And the principal name specified in the
+  configuration must be '*'. For example:
+
++---+
+  <property>
+    <name>hadoop.kms.authentication.kerberos.principal</name>
+    <value>*</value>
+  </property>
++---+
+
+  <<NOTE:>> If using HTTPS, the SSL certificate used by the KMS instance must
+  be configured to support multiple hostnames (see Java 7
+  <<<keytool>> SAN extension support for details on how to do this).
 
 *** HTTP Authentication Signature