libjava/java/security/KeyStore.java

   1 /* KeyStore.java --- Key Store Class
   2    Copyright (C) 1999, 2002, 2003 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.security;
  39 import java.io.InputStream;
  40 import java.io.IOException;
  41 import java.io.OutputStream;
  42 import java.security.cert.CertificateException;
  43 import java.util.Date;
  44 import java.util.Enumeration;
  45
  46 import gnu.java.security.Engine;
  47
  48 /**
  49  * Keystore represents an in-memory collection of keys and
  50  * certificates. There are two types of entries:
  51  *
  52  * <dl>
  53  * <dt>Key Entry</dt>
  54  *
  55  * <dd><p>This type of keystore entry store sensitive crytographic key
  56  * information in a protected format.Typically this is a secret
  57  * key or a private key with a certificate chain.</p></dd>
  58  *
  59  * <dt>Trusted Ceritificate Entry</dt>
  60  *
  61  * <dd><p>This type of keystore entry contains a single public key
  62  * certificate belonging to annother entity. It is called trusted
  63  * because the keystore owner trusts that the certificates
  64  * belongs to the subject (owner) of the certificate.</p></dd>
  65  * </dl>
  66  *
  67  * <p>Entries in a key store are referred to by their "alias": a simple
  68  * unique string.
  69  *
  70  * <p>The structure and persistentence of the key store is not
  71  * specified. Any method could be used to protect sensitive
  72  * (private or secret) keys. Smart cards or integrated
  73  * cryptographic engines could be used or the keystore could
  74  * be simply stored in a file.</p>
  75  *
  76  * @see java.security.cert.Certificate
  77  * @see Key
  78  */
  79 public class KeyStore
  80 {
  81
  82   // Constants and fields.
  83   // ------------------------------------------------------------------------
  84
  85   /** Service name for key stores. */
  86   private static final String KEY_STORE = "KeyStore";
  87
  88   private KeyStoreSpi keyStoreSpi;
  89   private Provider provider;
  90   private String type;
  91
  92   // Constructors.
  93   // ------------------------------------------------------------------------
  94
  95   /**
  96      Creates an instance of KeyStore
  97
  98      @param keyStoreSpi A KeyStore engine to use
  99      @param provider A provider to use
 100      @param type The type of KeyStore
 101    */
 102   protected KeyStore(KeyStoreSpi keyStoreSpi, Provider provider, String type)
 103   {
 104     this.keyStoreSpi = keyStoreSpi;
 105     this.provider = provider;
 106     this.type = type;
 107   }
 108
 109   // Class methods.
 110   // ------------------------------------------------------------------------
 111
 112   /**
 113    * Gets an instance of the KeyStore class representing
 114    * the specified keystore. If the type is not
 115    * found then, it throws KeyStoreException.
 116    *
 117    * @param type the type of keystore to choose
 118    * @return a KeyStore repesenting the desired type
 119    * @throws KeyStoreException if the type of keystore is not implemented
 120    *         by providers or the implementation cannot be instantiated.
 121    */
 122   public static KeyStore getInstance(String type) throws KeyStoreException
 123   {
 124     Provider[] p = Security.getProviders();
 125
 126     for (int i = 0; i < p.length; i++)
 127       {
 128         try
 129           {
 130             return getInstance(type, p[i]);
 131           }
 132         catch (KeyStoreException ignore)
 133           {
 134           }
 135       }
 136
 137     throw new KeyStoreException(type);
 138   }
 139
 140   /**
 141    * Gets an instance of the KeyStore class representing
 142    * the specified key store from the specified provider.
 143    * If the type is not found then, it throws KeyStoreException.
 144    * If the provider is not found, then it throws
 145    * NoSuchProviderException.
 146    *
 147    * @param type the type of keystore to choose
 148    * @param provider the provider name
 149    * @return a KeyStore repesenting the desired type
 150    * @throws KeyStoreException if the type of keystore is not
 151    *          implemented by the given provider
 152    * @throws NoSuchProviderException if the provider is not found
 153    * @throws IllegalArgumentException if the provider string is
 154    *           null or empty
 155    */
 156   public static KeyStore getInstance(String type, String provider)
 157     throws KeyStoreException, NoSuchProviderException
 158   {
 159     if (provider == null || provider.length() == 0)
 160       throw new IllegalArgumentException("Illegal provider");
 161
 162     Provider p = Security.getProvider(provider);
 163     if (p == null)
 164       throw new NoSuchProviderException();
 165
 166     return getInstance(type, p);
 167   }
 168
 169   /**
 170    * Gets an instance of the KeyStore class representing
 171    * the specified key store from the specified provider.
 172    * If the type is not found then, it throws KeyStoreException.
 173    * If the provider is not found, then it throws
 174    * NoSuchProviderException.
 175    *
 176    * @param type the type of keystore to choose
 177    * @param provider the keystore provider
 178    * @return a KeyStore repesenting the desired type
 179    * @throws KeyStoreException if the type of keystore is not
 180    *          implemented by the given provider
 181    * @throws IllegalArgumentException if the provider object is null
 182    * @since 1.4
 183    */
 184   public static KeyStore getInstance(String type, Provider provider)
 185     throws KeyStoreException
 186   {
 187     if (provider == null)
 188       throw new IllegalArgumentException("Illegal provider");
 189     try
 190       {
 191         return new KeyStore(
 192           (KeyStoreSpi) Engine.getInstance(KEY_STORE, type, provider),
 193           provider, type);
 194       }
 195     catch (NoSuchAlgorithmException nsae)
 196       {
 197         throw new KeyStoreException(type);
 198       }
 199     catch (java.lang.reflect.InvocationTargetException ite)
 200       {
 201         throw new KeyStoreException(type);
 202       }
 203     catch (ClassCastException cce)
 204       {
 205         throw new KeyStoreException(type);
 206       }
 207   }
 208
 209   /**
 210    * Returns the default KeyStore type. This method looks up the
 211    * type in <JAVA_HOME>/lib/security/java.security with the
 212    * property "keystore.type" or if that fails then "jks" .
 213    */
 214   public static final String getDefaultType()
 215   {
 216     // Security reads every property in java.security so it
 217     // will return this property if it exists.
 218     String tmp = Security.getProperty("keystore.type");
 219
 220     if (tmp == null)
 221       tmp = "jks";
 222
 223     return tmp;
 224   }
 225
 226   // Instance methods.
 227   // ------------------------------------------------------------------------
 228
 229   /**
 230      Gets the provider that the class is from.
 231
 232      @return the provider of this class
 233    */
 234   public final Provider getProvider()
 235   {
 236     return provider;
 237   }
 238
 239   /**
 240      Returns the type of the KeyStore supported
 241
 242      @return A string with the type of KeyStore
 243    */
 244   public final String getType()
 245   {
 246     return type;
 247   }
 248
 249   /**
 250      Returns the key associated with given alias using the
 251      supplied password.
 252
 253      @param alias an alias for the key to get
 254      @param password password to access key with
 255
 256      @return the requested key, or null otherwise
 257
 258      @throws NoSuchAlgorithmException if there is no algorithm
 259      for recovering the key
 260      @throws UnrecoverableKeyException key cannot be reocovered
 261      (wrong password).
 262    */
 263   public final Key getKey(String alias, char[]password)
 264     throws KeyStoreException, NoSuchAlgorithmException,
 265     UnrecoverableKeyException
 266   {
 267     return keyStoreSpi.engineGetKey(alias, password);
 268   }
 269
 270   /**
 271      Gets a Certificate chain for the specified alias.
 272
 273      @param alias the alias name
 274
 275      @return a chain of Certificates ( ordered from the user's
 276      certificate to the Certificate Authority's ) or
 277      null if the alias does not exist or there is no
 278      certificate chain for the alias ( the alias refers
 279      to a trusted certificate entry or there is no entry).
 280    */
 281   public final java.security.cert.
 282     Certificate[] getCertificateChain(String alias) throws KeyStoreException
 283   {
 284     return keyStoreSpi.engineGetCertificateChain(alias);
 285   }
 286
 287   /**
 288      Gets a Certificate for the specified alias.
 289
 290      If there is a trusted certificate entry then that is returned.
 291      it there is a key entry with a certificate chain then the
 292      first certificate is return or else null.
 293
 294      @param alias the alias name
 295
 296      @return a Certificate or null if the alias does not exist
 297      or there is no certificate for the alias
 298    */
 299   public final java.security.cert.Certificate getCertificate(String alias)
 300     throws KeyStoreException
 301   {
 302     return keyStoreSpi.engineGetCertificate(alias);
 303   }
 304
 305   /**
 306      Gets entry creation date for the specified alias.
 307
 308      @param alias the alias name
 309
 310      @returns the entry creation date or null
 311    */
 312   public final Date getCreationDate(String alias) throws KeyStoreException
 313   {
 314     return keyStoreSpi.engineGetCreationDate(alias);
 315   }
 316
 317   /**
 318      Assign the key to the alias in the keystore, protecting it
 319      with the given password. It will overwrite an existing
 320      entry and if the key is a PrivateKey, also add the
 321      certificate chain representing the corresponding public key.
 322
 323      @param alias the alias name
 324      @param key the key to add
 325      @password the password to protect with
 326      @param chain the certificate chain for the corresponding
 327      public key
 328
 329      @throws KeyStoreException if it fails
 330    */
 331   public final void setKeyEntry(String alias, Key key, char[]password,
 332                                 java.security.cert.
 333                                 Certificate[]chain) throws KeyStoreException
 334   {
 335     keyStoreSpi.engineSetKeyEntry(alias, key, password, chain);
 336   }
 337
 338   /**
 339      Assign the key to the alias in the keystore. It will overwrite
 340      an existing entry and if the key is a PrivateKey, also
 341      add the certificate chain representing the corresponding
 342      public key.
 343
 344      @param alias the alias name
 345      @param key the key to add
 346      @param chain the certificate chain for the corresponding
 347      public key
 348
 349      @throws KeyStoreException if it fails
 350    */
 351   public final void setKeyEntry(String alias, byte[]key,
 352                                 java.security.cert.
 353                                 Certificate[]chain) throws KeyStoreException
 354   {
 355     keyStoreSpi.engineSetKeyEntry(alias, key, chain);
 356   }
 357
 358   /**
 359      Assign the certificate to the alias in the keystore. It
 360      will overwrite an existing entry.
 361
 362      @param alias the alias name
 363      @param cert the certificate to add
 364
 365      @throws KeyStoreException if it fails
 366    */
 367   public final void setCertificateEntry(String alias,
 368                                         java.security.cert.
 369                                         Certificate cert) throws
 370     KeyStoreException
 371   {
 372     keyStoreSpi.engineSetCertificateEntry(alias, cert);
 373   }
 374
 375   /**
 376      Deletes the entry for the specified entry.
 377
 378      @param alias the alias name
 379
 380      @throws KeyStoreException if it fails
 381    */
 382   public final void deleteEntry(String alias) throws KeyStoreException
 383   {
 384     keyStoreSpi.engineDeleteEntry(alias);
 385   }
 386
 387   /**
 388      Generates a list of all the aliases in the keystore.
 389
 390      @return an Enumeration of the aliases
 391    */
 392   public final Enumeration aliases() throws KeyStoreException
 393   {
 394     return keyStoreSpi.engineAliases();
 395   }
 396
 397   /**
 398      Determines if the keystore contains the specified alias.
 399
 400      @param alias the alias name
 401
 402      @return true if it contains the alias, false otherwise
 403    */
 404   public final boolean containsAlias(String alias) throws KeyStoreException
 405   {
 406     return keyStoreSpi.engineContainsAlias(alias);
 407   }
 408
 409   /**
 410      Returns the number of entries in the keystore.
 411
 412      @returns the number of keystore entries.
 413    */
 414   public final int size() throws KeyStoreException
 415   {
 416     return keyStoreSpi.engineSize();
 417   }
 418
 419   /**
 420      Determines if the keystore contains a key entry for
 421      the specified alias.
 422
 423      @param alias the alias name
 424
 425      @return true if it is a key entry, false otherwise
 426    */
 427   public final boolean isKeyEntry(String alias) throws KeyStoreException
 428   {
 429     return keyStoreSpi.engineIsKeyEntry(alias);
 430   }
 431
 432
 433   /**
 434      Determines if the keystore contains a certificate entry for
 435      the specified alias.
 436
 437      @param alias the alias name
 438
 439      @return true if it is a certificate entry, false otherwise
 440    */
 441   public final boolean isCertificateEntry(String alias)
 442     throws KeyStoreException
 443   {
 444     return keyStoreSpi.engineIsCertificateEntry(alias);
 445   }
 446
 447   /**
 448      Determines if the keystore contains the specified certificate
 449      entry and returns the alias.
 450
 451      It checks every entry and for a key entry checks only the
 452      first certificate in the chain.
 453
 454      @param cert Certificate to look for
 455
 456      @return alias of first matching certificate, null if it
 457      does not exist.
 458    */
 459   public final String getCertificateAlias(java.security.cert.Certificate cert)
 460     throws KeyStoreException
 461   {
 462     return keyStoreSpi.engineGetCertificateAlias(cert);
 463   }
 464
 465   /**
 466      Stores the keystore in the specified output stream and it
 467      uses the specified key it keep it secure.
 468
 469      @param stream the output stream to save the keystore to
 470      @param password the password to protect the keystore integrity with
 471
 472      @throws IOException if an I/O error occurs.
 473      @throws NoSuchAlgorithmException the data integrity algorithm
 474      used cannot be found.
 475      @throws CertificateException if any certificates could not be
 476      stored in the output stream.
 477    */
 478   public final void store(OutputStream stream, char[]password)
 479     throws KeyStoreException, IOException, NoSuchAlgorithmException,
 480     CertificateException
 481   {
 482     keyStoreSpi.engineStore(stream, password);
 483   }
 484
 485   /**
 486      Loads the keystore from the specified input stream and it
 487      uses the specified password to check for integrity if supplied.
 488
 489      @param stream the input stream to load the keystore from
 490      @param password the password to check the keystore integrity with
 491
 492      @throws IOException if an I/O error occurs.
 493      @throws NoSuchAlgorithmException the data integrity algorithm
 494      used cannot be found.
 495      @throws CertificateException if any certificates could not be
 496      stored in the output stream.
 497    */
 498   public final void load(InputStream stream, char[]password)
 499     throws IOException, NoSuchAlgorithmException, CertificateException
 500   {
 501     keyStoreSpi.engineLoad(stream, password);
 502   }
 503
 504 }