| /* |
| * Copyright (c) 2011, 2015, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package javax.security.auth.kerberos; |
| |
| import java.io.File; |
| import java.security.AccessControlException; |
| import java.util.Objects; |
| import sun.security.krb5.EncryptionKey; |
| import sun.security.krb5.KerberosSecrets; |
| import sun.security.krb5.PrincipalName; |
| import sun.security.krb5.RealmException; |
| |
| /** |
| * This class encapsulates a keytab file. |
| * <p> |
| * A Kerberos JAAS login module that obtains long term secret keys from a |
| * keytab file should use this class. The login module will store |
| * an instance of this class in the private credential set of a |
| * {@link javax.security.auth.Subject Subject} during the commit phase of the |
| * authentication process. |
| * <p> |
| * If a {@code KeyTab} object is obtained from {@link #getUnboundInstance()} |
| * or {@link #getUnboundInstance(java.io.File)}, it is unbound and thus can be |
| * used by any service principal. Otherwise, if it's obtained from |
| * {@link #getInstance(KerberosPrincipal)} or |
| * {@link #getInstance(KerberosPrincipal, java.io.File)}, it is bound to the |
| * specific service principal and can only be used by it. |
| * <p> |
| * Please note the constructors {@link #getInstance()} and |
| * {@link #getInstance(java.io.File)} were created when there was no support |
| * for unbound keytabs. These methods should not be used anymore. An object |
| * created with either of these methods are considered to be bound to an |
| * unknown principal, which means, its {@link #isBound()} returns true and |
| * {@link #getPrincipal()} returns null. |
| * <p> |
| * It might be necessary for the application to be granted a |
| * {@link javax.security.auth.PrivateCredentialPermission |
| * PrivateCredentialPermission} if it needs to access the {@code KeyTab} |
| * instance from a {@code Subject}. This permission is not needed when the |
| * application depends on the default JGSS Kerberos mechanism to access the |
| * {@code KeyTab}. In that case, however, the application will need an appropriate |
| * {@link javax.security.auth.kerberos.ServicePermission ServicePermission}. |
| * <p> |
| * The keytab file format is described at |
| * <a href="http://www.ioplex.com/utilities/keytab.txt"> |
| * http://www.ioplex.com/utilities/keytab.txt</a>. |
| * |
| * @since 1.7 |
| */ |
| public final class KeyTab { |
| |
| /* |
| * Impl notes: |
| * |
| * This class is only a name, a permanent link to the keytab source |
| * (can be missing). Itself has no content. In order to read content, |
| * take a snapshot and read from it. |
| * |
| * The snapshot is of type sun.security.krb5.internal.ktab.KeyTab, which |
| * contains the content of the keytab file when the snapshot is taken. |
| * Itself has no refresh function and mostly an immutable class (except |
| * for the create/add/save methods only used by the ktab command). |
| */ |
| |
| // Source, null if using the default one. Note that the default name |
| // is maintained in snapshot, this field is never "resolved". |
| private final File file; |
| |
| // Bound user: normally from the "principal" value in a JAAS krb5 |
| // login conf. Will be null if it's "*". |
| private final KerberosPrincipal princ; |
| |
| private final boolean bound; |
| |
| // Set up JavaxSecurityAuthKerberosAccess in KerberosSecrets |
| static { |
| KerberosSecrets.setJavaxSecurityAuthKerberosAccess( |
| new JavaxSecurityAuthKerberosAccessImpl()); |
| } |
| |
| private KeyTab(KerberosPrincipal princ, File file, boolean bound) { |
| this.princ = princ; |
| this.file = file; |
| this.bound = bound; |
| } |
| |
| /** |
| * Returns a {@code KeyTab} instance from a {@code File} object |
| * that is bound to an unknown service principal. |
| * <p> |
| * The result of this method is never null. This method only associates |
| * the returned {@code KeyTab} object with the file and does not read it. |
| * <p> |
| * Developers should call {@link #getInstance(KerberosPrincipal,File)} |
| * when the bound service principal is known. |
| * @param file the keytab {@code File} object, must not be null |
| * @return the keytab instance |
| * @throws NullPointerException if the {@code file} argument is null |
| */ |
| public static KeyTab getInstance(File file) { |
| if (file == null) { |
| throw new NullPointerException("file must be non null"); |
| } |
| return new KeyTab(null, file, true); |
| } |
| |
| /** |
| * Returns an unbound {@code KeyTab} instance from a {@code File} |
| * object. |
| * <p> |
| * The result of this method is never null. This method only associates |
| * the returned {@code KeyTab} object with the file and does not read it. |
| * @param file the keytab {@code File} object, must not be null |
| * @return the keytab instance |
| * @throws NullPointerException if the file argument is null |
| * @since 1.8 |
| */ |
| public static KeyTab getUnboundInstance(File file) { |
| if (file == null) { |
| throw new NullPointerException("file must be non null"); |
| } |
| return new KeyTab(null, file, false); |
| } |
| |
| /** |
| * Returns a {@code KeyTab} instance from a {@code File} object |
| * that is bound to the specified service principal. |
| * <p> |
| * The result of this method is never null. This method only associates |
| * the returned {@code KeyTab} object with the file and does not read it. |
| * @param princ the bound service principal, must not be null |
| * @param file the keytab {@code File} object, must not be null |
| * @return the keytab instance |
| * @throws NullPointerException if either of the arguments is null |
| * @since 1.8 |
| */ |
| public static KeyTab getInstance(KerberosPrincipal princ, File file) { |
| if (princ == null) { |
| throw new NullPointerException("princ must be non null"); |
| } |
| if (file == null) { |
| throw new NullPointerException("file must be non null"); |
| } |
| return new KeyTab(princ, file, true); |
| } |
| |
| /** |
| * Returns the default {@code KeyTab} instance that is bound |
| * to an unknown service principal. |
| * <p> |
| * The result of this method is never null. This method only associates |
| * the returned {@code KeyTab} object with the default keytab file and |
| * does not read it. |
| * <p> |
| * Developers should call {@link #getInstance(KerberosPrincipal)} |
| * when the bound service principal is known. |
| * @return the default keytab instance. |
| */ |
| public static KeyTab getInstance() { |
| return new KeyTab(null, null, true); |
| } |
| |
| /** |
| * Returns the default unbound {@code KeyTab} instance. |
| * <p> |
| * The result of this method is never null. This method only associates |
| * the returned {@code KeyTab} object with the default keytab file and |
| * does not read it. |
| * @return the default keytab instance |
| * @since 1.8 |
| */ |
| public static KeyTab getUnboundInstance() { |
| return new KeyTab(null, null, false); |
| } |
| |
| /** |
| * Returns the default {@code KeyTab} instance that is bound |
| * to the specified service principal. |
| * <p> |
| * The result of this method is never null. This method only associates |
| * the returned {@code KeyTab} object with the default keytab file and |
| * does not read it. |
| * @param princ the bound service principal, must not be null |
| * @return the default keytab instance |
| * @throws NullPointerException if {@code princ} is null |
| * @since 1.8 |
| */ |
| public static KeyTab getInstance(KerberosPrincipal princ) { |
| if (princ == null) { |
| throw new NullPointerException("princ must be non null"); |
| } |
| return new KeyTab(princ, null, true); |
| } |
| |
| // Takes a snapshot of the keytab content. This method is called by |
| // JavaxSecurityAuthKerberosAccessImpl so no more private |
| sun.security.krb5.internal.ktab.KeyTab takeSnapshot() { |
| try { |
| return sun.security.krb5.internal.ktab.KeyTab.getInstance(file); |
| } catch (AccessControlException ace) { |
| if (file != null) { |
| // It's OK to show the name if caller specified it |
| throw ace; |
| } else { |
| AccessControlException ace2 = new AccessControlException( |
| "Access to default keytab denied (modified exception)"); |
| ace2.setStackTrace(ace.getStackTrace()); |
| throw ace2; |
| } |
| } |
| } |
| |
| /** |
| * Returns fresh keys for the given Kerberos principal. |
| * <p> |
| * Implementation of this method should make sure the returned keys match |
| * the latest content of the keytab file. The result is a newly created |
| * copy that can be modified by the caller without modifying the keytab |
| * object. The caller should {@link KerberosKey#destroy() destroy} the |
| * result keys after they are used. |
| * <p> |
| * Please note that the keytab file can be created after the |
| * {@code KeyTab} object is instantiated and its content may change over |
| * time. Therefore, an application should call this method only when it |
| * needs to use the keys. Any previous result from an earlier invocation |
| * could potentially be expired. |
| * <p> |
| * If there is any error (say, I/O error or format error) |
| * during the reading process of the keytab file, a saved result should be |
| * returned. If there is no saved result (say, this is the first time this |
| * method is called, or, all previous read attempts failed), an empty array |
| * should be returned. This can make sure the result is not drastically |
| * changed during the (probably slow) update of the keytab file. |
| * <p> |
| * Each time this method is called and the reading of the file succeeds |
| * with no exception (say, I/O error or file format error), |
| * the result should be saved for {@code principal}. The implementation can |
| * also save keys for other principals having keys in the same keytab object |
| * if convenient. |
| * <p> |
| * Any unsupported key read from the keytab is ignored and not included |
| * in the result. |
| * <p> |
| * If this keytab is bound to a specific principal, calling this method on |
| * another principal will return an empty array. |
| * |
| * @param principal the Kerberos principal, must not be null. |
| * @return the keys (never null, may be empty) |
| * @throws NullPointerException if the {@code principal} |
| * argument is null |
| * @throws SecurityException if a security manager exists and the read |
| * access to the keytab file is not permitted |
| */ |
| public KerberosKey[] getKeys(KerberosPrincipal principal) { |
| try { |
| if (princ != null && !principal.equals(princ)) { |
| return new KerberosKey[0]; |
| } |
| PrincipalName pn = new PrincipalName(principal.getName()); |
| EncryptionKey[] keys = takeSnapshot().readServiceKeys(pn); |
| KerberosKey[] kks = new KerberosKey[keys.length]; |
| for (int i=0; i<kks.length; i++) { |
| Integer tmp = keys[i].getKeyVersionNumber(); |
| kks[i] = new KerberosKey( |
| principal, |
| keys[i].getBytes(), |
| keys[i].getEType(), |
| tmp == null ? 0 : tmp.intValue()); |
| keys[i].destroy(); |
| } |
| return kks; |
| } catch (RealmException re) { |
| return new KerberosKey[0]; |
| } |
| } |
| |
| EncryptionKey[] getEncryptionKeys(PrincipalName principal) { |
| return takeSnapshot().readServiceKeys(principal); |
| } |
| |
| /** |
| * Checks if the keytab file exists. Implementation of this method |
| * should make sure that the result matches the latest status of the |
| * keytab file. |
| * <p> |
| * The caller can use the result to determine if it should fallback to |
| * another mechanism to read the keys. |
| * @return true if the keytab file exists; false otherwise. |
| * @throws SecurityException if a security manager exists and the read |
| * access to the keytab file is not permitted |
| */ |
| public boolean exists() { |
| return !takeSnapshot().isMissing(); |
| } |
| |
| /** |
| * Returns an informative textual representation of this {@code KeyTab}. |
| * |
| * @return an informative textual representation of this {@code KeyTab}. |
| */ |
| public String toString() { |
| String s = (file == null) ? "Default keytab" : file.toString(); |
| if (!bound) return s; |
| else if (princ == null) return s + " for someone"; |
| else return s + " for " + princ; |
| } |
| |
| /** |
| * Returns a hash code for this {@code KeyTab}. |
| * |
| * @return a hash code for this {@code KeyTab}. |
| */ |
| public int hashCode() { |
| return Objects.hash(file, princ, bound); |
| } |
| |
| /** |
| * Compares the specified object with this {@code KeyTab} for equality. |
| * Returns true if the given object is also a |
| * {@code KeyTab} and the two |
| * {@code KeyTab} instances are equivalent. |
| * |
| * @param other the object to compare to |
| * @return true if the specified object is equal to this {@code KeyTab} |
| */ |
| public boolean equals(Object other) { |
| if (other == this) |
| return true; |
| |
| if (! (other instanceof KeyTab)) { |
| return false; |
| } |
| |
| KeyTab otherKtab = (KeyTab) other; |
| return Objects.equals(otherKtab.princ, princ) && |
| Objects.equals(otherKtab.file, file) && |
| bound == otherKtab.bound; |
| } |
| |
| /** |
| * Returns the service principal this {@code KeyTab} object |
| * is bound to. Returns {@code null} if it's not bound. |
| * <p> |
| * Please note the deprecated constructors create a {@code KeyTab} object |
| * bound for some unknown principal. In this case, this method also returns |
| * null. User can call {@link #isBound()} to verify this case. |
| * @return the service principal |
| * @since 1.8 |
| */ |
| public KerberosPrincipal getPrincipal() { |
| return princ; |
| } |
| |
| /** |
| * Returns if the keytab is bound to a principal |
| * @return if the keytab is bound to a principal |
| * @since 1.8 |
| */ |
| public boolean isBound() { |
| return bound; |
| } |
| } |