KerberosKey


1   /*
2    * @(#)KerberosKey.java 1.17 04/01/13
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7     
8   package javax.security.auth.kerberos;
9   
10  import javax.crypto.SecretKey;
11  import javax.security.auth.Destroyable  ;
12  import javax.security.auth.DestroyFailedException  ;
13  
14  /**
15   * This class encapsulates a long term secret key for a Kerberos
16   * principal.<p>
17   *
18   * All Kerberos JAAS login modules that obtain a principal's password and
19   * generate the secret key from it should use this class. Where available,
20   * the login module might even read this secret key directly from a
21   * Kerberos "keytab". Sometimes, such as when authenticating a server in
22   * the absence of user-to-user authentication, the login module will store 
23   * an instance of this class in the private credential set of a
24   * {@link javax.security.auth.Subject Subject} during the commit phase of the
25   * authentication process.<p>
26   *
27   * It might be necessary for the application to be granted a
28   * {@link javax.security.auth.PrivateCredentialPermission 
29   * PrivateCredentialPermission} if it needs to access the KerberosKey
30   * instance from a Subject. This permission is not needed when the 
31   * application depends on the default JGSS Kerberos mechanism to access the 
32   * KerberosKey. In that case, however, the application will need an 
33   * appropriate 
34   * {@link javax.security.auth.kerberos.ServicePermission ServicePermission}.
35   *
36   * @author Mayank Upadhyay
37   * @version 1.17, 01/13/04
38   * @since 1.4
39   */
40  public class KerberosKey implements SecretKey, Destroyable   {
41  
42      private static final long serialVersionUID = -4625402278148246993L;
43  
44     /**
45       * The principal that this secret key belongs to.
46       *
47       * @serial
48       */
49      private KerberosPrincipal   principal;
50  
51     /**
52       * the version number of this secret key
53       *
54       * @serial
55       */
56      private int versionNum;
57  
58     /**
59      * <code>KeyImpl</code> is serialized by writing out the ASN1 Encoded bytes 
60      *           of the  encryption key. The ASN1 encoding is defined in 
61      *           RFC1510 and as  follows:
62      *           <pre>
63      *           EncryptionKey ::=   SEQUENCE {
64      *               keytype[0]    INTEGER,
65      *               keyvalue[1]   OCTET STRING      
66      *               }
67      *           </pre>
68      *
69      * @serial
70      */
71  
72      private KeyImpl   key;
73      private transient boolean destroyed = false;
74  
75      /**
76       * Constructs a KerberosKey from the given bytes when the key type and
77       * key version number are known. This can be used when reading the secret
78       * key information from a Kerberos "keytab".
79       * 
80       * @param principal the principal that this secret key belongs to
81       * @param keyBytes the raw bytes for the secret key
82       * @param keyType the key type for the secret key as defined by the
83       * Kerberos protocol specification.
84       * @param versionNum the version number of this secret key
85       */
86      public KerberosKey(KerberosPrincipal   principal,
87                 byte[] keyBytes, 
88                 int keyType,
89                 int versionNum) {
90      this.principal = principal;
91      this.versionNum = versionNum;
92      key = new KeyImpl  (keyBytes, keyType);
93      }
94  
95      /**
96       * Constructs a KerberosKey from a principal's password.
97       *
98       * @param principal the principal that this password belongs to
99       * @param password the password that should be used to compute the key
100      * @param algorithm the name for the algorithm that this key will be
101      * used for. This parameter may be null in which case the default
102      * algorithm "DES" will be assumed.
103      * @throws IllegalArgumentException if the name of the 
104      * algorithm passed is unsupported. 
105      */
106     public KerberosKey(KerberosPrincipal   principal,
107                char[] password,
108                String   algorithm) {
109 
110     this.principal = principal;
111     // Pass principal in for salt
112     key = new KeyImpl  (principal, password, algorithm);
113     }
114 
115     /**
116      * Returns the principal that this key belongs to.
117      *
118      * @return the principal this key belongs to.
119      */
120     public final KerberosPrincipal   getPrincipal() {
121     if (destroyed)
122         throw new IllegalStateException  ("This key is no longer valid");
123     return principal;
124     }
125 
126     /**
127      * Returns the key version number.
128      *
129      * @return the key version number.
130      */
131     public final int getVersionNumber() {
132     if (destroyed)
133         throw new IllegalStateException  ("This key is no longer valid");
134     return versionNum;
135     }
136 
137     /**
138      * Returns the key type for this long-term key.
139      *
140      * @return the key type.
141      */
142     public final int getKeyType() {
143     if (destroyed)
144         throw new IllegalStateException  ("This key is no longer valid");
145     return key.getKeyType();
146     }
147 
148     /*
149      * Methods from java.security.Key
150      */
151     
152     /** 
153      * Returns the standard algorithm name for this key. For 
154      * example, "DES" would indicate that this key is a DES key. 
155      * See Appendix A in the <a HREF= 
156      * "../../../../../guide/security/CryptoSpec.html#AppA"> 
157      * Java Cryptography Architecture API Specification &amp; Reference
158      * </a> 
159      * for information about standard algorithm names.
160      * 
161      * @return the name of the algorithm associated with this key.
162      */
163     public final String   getAlgorithm() {
164     if (destroyed)
165         throw new IllegalStateException  ("This key is no longer valid");
166     return key.getAlgorithm();
167     }
168     
169     /**
170      * Returns the name of the encoding format for this secret key.
171      *
172      * @return the String "RAW"
173      */
174     public final String   getFormat() {
175     if (destroyed)
176         throw new IllegalStateException  ("This key is no longer valid");
177     return key.getFormat();
178     }
179     
180     /**
181      * Returns the key material of this secret key.
182      *
183      * @return the key material
184      */
185     public final byte[] getEncoded() {
186     if (destroyed)
187         throw new IllegalStateException  ("This key is no longer valid");
188     return key.getEncoded();
189     }
190 
191     /**
192      * Destroys this key. A call to any of its other methods after this
193      * will cause an  IllegalStateException to be thrown.
194      *
195      * @throws DestroyFailedException if some error occurs while destorying 
196      * this key.
197      */
198     public void destroy() throws DestroyFailedException   {
199     if (!destroyed) {
200         key.destroy();
201         principal = null;
202         destroyed = true;
203     }
204     }
205 
206 
207     /** Determines if this key has been destroyed.*/
208     public boolean isDestroyed() {
209     return destroyed;
210     }
211    
212    public String   toString() {
213 
214     return "Kerberos Principal " + principal.toString() +
215         "Key Version " + versionNum +
216         "key "  + key.toString();
217    }
218 
219 }
220
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags