| /* |
| * Copyright (c) 2000, 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.util.Arrays; |
| import javax.crypto.SecretKey; |
| import javax.security.auth.DestroyFailedException; |
| |
| /** |
| * This class encapsulates a long term secret key for a Kerberos |
| * principal.<p> |
| * |
| * A {@code KerberosKey} object includes an EncryptionKey, a |
| * {@link KerberosPrincipal} as its owner, and the version number |
| * of the key.<p> |
| * |
| * An EncryptionKey is defined in Section 4.2.9 of the Kerberos Protocol |
| * Specification (<a href=http://www.ietf.org/rfc/rfc4120.txt>RFC 4120</a>) as: |
| * <pre> |
| * EncryptionKey ::= SEQUENCE { |
| * keytype [0] Int32 -- actually encryption type --, |
| * keyvalue [1] OCTET STRING |
| * } |
| * </pre> |
| * The key material of a {@code KerberosKey} is defined as the value |
| * of the {@code keyValue} above.<p> |
| * |
| * All Kerberos JAAS login modules that obtain a principal's password and |
| * generate the secret key from it should use this class. |
| * Sometimes, such as when authenticating a server in |
| * the absence of user-to-user authentication, 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> |
| * |
| * A Kerberos service using a keytab to read secret keys should use |
| * the {@link KeyTab} class, where latest keys can be read when needed.<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 KerberosKey} |
| * instance from a Subject. This permission is not needed when the |
| * application depends on the default JGSS Kerberos mechanism to access the |
| * {@code KerberosKey}. In that case, however, the application will need an |
| * appropriate |
| * {@link javax.security.auth.kerberos.ServicePermission ServicePermission}.<p> |
| * |
| * When creating a {@code KerberosKey} using the |
| * {@link #KerberosKey(KerberosPrincipal, char[], String)} constructor, |
| * an implementation may accept non-IANA algorithm names (For example, |
| * "ArcFourMac" for "rc4-hmac"), but the {@link #getAlgorithm} method |
| * must always return the IANA algorithm name. |
| * |
| * @implNote Old algorithm names used before JDK 9 are supported in the |
| * {@link #KerberosKey(KerberosPrincipal, char[], String)} constructor in this |
| * implementation for compatibility reasons, which are "DES" (and null) for |
| * "des-cbc-md5", "DESede" for "des3-cbc-sha1-kd", "ArcFourHmac" for "rc4-hmac", |
| * "AES128" for "aes128-cts-hmac-sha1-96", and "AES256" for |
| * "aes256-cts-hmac-sha1-96". |
| * |
| * @author Mayank Upadhyay |
| * @since 1.4 |
| */ |
| public class KerberosKey implements SecretKey { |
| |
| private static final long serialVersionUID = -4625402278148246993L; |
| |
| /** |
| * The principal that this secret key belongs to. |
| * |
| * @serial |
| */ |
| private KerberosPrincipal principal; |
| |
| /** |
| * the version number of this secret key |
| * |
| * @serial |
| */ |
| private final int versionNum; |
| |
| /** |
| * {@code KeyImpl} is serialized by writing out the ASN.1 encoded bytes |
| * of the encryption key. |
| * |
| * @serial |
| */ |
| |
| private KeyImpl key; |
| private transient boolean destroyed = false; |
| |
| /** |
| * Constructs a {@code KerberosKey} from the given bytes when the key type |
| * and key version number are known. This can be used when reading the |
| * secret key information from a Kerberos "keytab". |
| * |
| * @param principal the principal that this secret key belongs to |
| * @param keyBytes the key material for the secret key |
| * @param keyType the key type for the secret key as defined by the |
| * Kerberos protocol specification. |
| * @param versionNum the version number of this secret key |
| */ |
| public KerberosKey(KerberosPrincipal principal, |
| byte[] keyBytes, |
| int keyType, |
| int versionNum) { |
| this.principal = principal; |
| this.versionNum = versionNum; |
| key = new KeyImpl(keyBytes, keyType); |
| } |
| |
| /** |
| * Constructs a {@code KerberosKey} from a principal's password using the |
| * specified algorithm name. The algorithm name (case insensitive) should |
| * be provided as the encryption type string defined on the IANA |
| * <a href="https://www.iana.org/assignments/kerberos-parameters/kerberos-parameters.xhtml#kerberos-parameters-1">Kerberos Encryption Type Numbers</a> |
| * page. The version number of the key generated will be 0. |
| * |
| * @param principal the principal that this password belongs to |
| * @param password the password that should be used to compute the key |
| * @param algorithm the name for the algorithm that this key will be |
| * used for |
| * @throws IllegalArgumentException if the name of the |
| * algorithm passed is unsupported. |
| */ |
| public KerberosKey(KerberosPrincipal principal, |
| char[] password, |
| String algorithm) { |
| |
| this.principal = principal; |
| this.versionNum = 0; |
| // Pass principal in for salt |
| key = new KeyImpl(principal, password, algorithm); |
| } |
| |
| /** |
| * Returns the principal that this key belongs to. |
| * |
| * @return the principal this key belongs to. |
| * @throws IllegalStateException if the key is destroyed |
| */ |
| public final KerberosPrincipal getPrincipal() { |
| if (destroyed) { |
| throw new IllegalStateException("This key is no longer valid"); |
| } |
| return principal; |
| } |
| |
| /** |
| * Returns the key version number. |
| * |
| * @return the key version number. |
| * @throws IllegalStateException if the key is destroyed |
| */ |
| public final int getVersionNumber() { |
| if (destroyed) { |
| throw new IllegalStateException("This key is no longer valid"); |
| } |
| return versionNum; |
| } |
| |
| /** |
| * Returns the key type for this long-term key. |
| * |
| * @return the key type. |
| * @throws IllegalStateException if the key is destroyed |
| */ |
| public final int getKeyType() { |
| // KeyImpl already checked if destroyed |
| return key.getKeyType(); |
| } |
| |
| /* |
| * Methods from java.security.Key |
| */ |
| |
| /** |
| * Returns the standard algorithm name for this key. The algorithm names |
| * are the encryption type string defined on the IANA |
| * <a href="https://www.iana.org/assignments/kerberos-parameters/kerberos-parameters.xhtml#kerberos-parameters-1">Kerberos Encryption Type Numbers</a> |
| * page. |
| * <p> |
| * This method can return the following value not defined on the IANA page: |
| * <ol> |
| * <li>none: for etype equal to 0</li> |
| * <li>unknown: for etype greater than 0 but unsupported by |
| * the implementation</li> |
| * <li>private: for etype smaller than 0</li> |
| * </ol> |
| * |
| * @return the name of the algorithm associated with this key. |
| * @throws IllegalStateException if the key is destroyed |
| */ |
| public final String getAlgorithm() { |
| // KeyImpl already checked if destroyed |
| return key.getAlgorithm(); |
| } |
| |
| /** |
| * Returns the name of the encoding format for this secret key. |
| * |
| * @return the String "RAW" |
| * @throws IllegalStateException if the key is destroyed |
| */ |
| public final String getFormat() { |
| // KeyImpl already checked if destroyed |
| return key.getFormat(); |
| } |
| |
| /** |
| * Returns the key material of this secret key. |
| * |
| * @return the key material |
| * @throws IllegalStateException if the key is destroyed |
| */ |
| public final byte[] getEncoded() { |
| // KeyImpl already checked if destroyed |
| return key.getEncoded(); |
| } |
| |
| /** |
| * Destroys this key by clearing out the key material of this secret key. |
| * |
| * @throws DestroyFailedException if some error occurs while destorying |
| * this key. |
| */ |
| public void destroy() throws DestroyFailedException { |
| if (!destroyed) { |
| key.destroy(); |
| principal = null; |
| destroyed = true; |
| } |
| } |
| |
| |
| /** Determines if this key has been destroyed.*/ |
| public boolean isDestroyed() { |
| return destroyed; |
| } |
| |
| /** |
| * Returns an informative textual representation of this {@code KerberosKey}. |
| * |
| * @return an informative textual representation of this {@code KerberosKey}. |
| */ |
| public String toString() { |
| if (destroyed) { |
| return "Destroyed KerberosKey"; |
| } |
| return "Kerberos Principal " + principal + |
| "Key Version " + versionNum + |
| "key " + key.toString(); |
| } |
| |
| /** |
| * Returns a hash code for this {@code KerberosKey}. |
| * |
| * @return a hash code for this {@code KerberosKey}. |
| * @since 1.6 |
| */ |
| public int hashCode() { |
| int result = 17; |
| if (isDestroyed()) { |
| return result; |
| } |
| result = 37 * result + Arrays.hashCode(getEncoded()); |
| result = 37 * result + getKeyType(); |
| if (principal != null) { |
| result = 37 * result + principal.hashCode(); |
| } |
| return result * 37 + versionNum; |
| } |
| |
| /** |
| * Compares the specified object with this {@code KerberosKey} for |
| * equality. Returns true if the given object is also a |
| * {@code KerberosKey} and the two |
| * {@code KerberosKey} instances are equivalent. |
| * A destroyed {@code KerberosKey} object is only equal to itself. |
| * |
| * @param other the object to compare to |
| * @return true if the specified object is equal to this {@code KerberosKey}, |
| * false otherwise. |
| * @since 1.6 |
| */ |
| public boolean equals(Object other) { |
| |
| if (other == this) { |
| return true; |
| } |
| |
| if (! (other instanceof KerberosKey)) { |
| return false; |
| } |
| |
| KerberosKey otherKey = ((KerberosKey) other); |
| if (isDestroyed() || otherKey.isDestroyed()) { |
| return false; |
| } |
| |
| if (versionNum != otherKey.getVersionNumber() || |
| getKeyType() != otherKey.getKeyType() || |
| !Arrays.equals(getEncoded(), otherKey.getEncoded())) { |
| return false; |
| } |
| |
| if (principal == null) { |
| if (otherKey.getPrincipal() != null) { |
| return false; |
| } |
| } else { |
| if (!principal.equals(otherKey.getPrincipal())) { |
| return false; |
| } |
| } |
| |
| return true; |
| } |
| } |
