libjava/java/security/KeyStore.java

   1 /* KeyStore.java --- Key Store Class
   2    Copyright (C) 1999, 2002 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 /**
  47    Keystore represents an in-memory collection of keys and
  48    certificates. There are two types of entries:
  49
  50    * Key Entry
  51
  52    This type of keystore entry store sensitive crytographic key
  53    information in a protected format.Typically this is a secret
  54    key or a private key with a certificate chain.
  55
  56
  57    * Trusted Ceritificate Entry
  58
  59    This type of keystore entry contains a single public key
  60    certificate belonging to annother entity. It is called trusted
  61    because the keystore owner trusts that the certificates
  62    belongs to the subject (owner) of the certificate.
  63
  64    The keystore contains an "alias" string for each entry.
  65
  66    The structure and persistentence of the key store is not
  67    specified. Any method could be used to protect sensitive
  68    (private or secret) keys. Smart cards or integrated
  69    cryptographic engines could be used or the keystore could
  70    be simply stored in a file.
  71  */
  72 public class KeyStore
  73 {
  74   private KeyStoreSpi keyStoreSpi;
  75   private Provider provider;
  76   private String type;
  77
  78   /**
  79      Creates an instance of KeyStore
  80
  81      @param keyStoreSpi A KeyStore engine to use
  82      @param provider A provider to use
  83      @param type The type of KeyStore
  84    */
  85   protected KeyStore(KeyStoreSpi keyStoreSpi, Provider provider, String type)
  86   {
  87     this.keyStoreSpi = keyStoreSpi;
  88     this.provider = provider;
  89     this.type = type;
  90   }
  91
  92   /**
  93      Gets an instance of the KeyStore class representing
  94      the specified keystore. If the type is not
  95      found then, it throws KeyStoreException.
  96
  97      @param type the type of keystore to choose
  98
  99      @return a KeyStore repesenting the desired type
 100
 101      @throws KeyStoreException if the type of keystore is not implemented by providers
 102    */
 103   public static KeyStore getInstance(String type) throws KeyStoreException
 104   {
 105     Provider[] p = Security.getProviders();
 106
 107     for (int i = 0; i < p.length; i++)
 108       {
 109         String classname = p[i].getProperty("KeyStore." + type);
 110         if (classname != null)
 111           return getInstance(classname, type, p[i]);
 112       }
 113
 114     throw new KeyStoreException(type);
 115   }
 116
 117   /**
 118      Gets an instance of the KeyStore class representing
 119      the specified key store from the specified provider.
 120      If the type is not found then, it throws KeyStoreException.
 121      If the provider is not found, then it throws
 122      NoSuchProviderException.
 123
 124      @param type the type of keystore to choose
 125      @param provider the provider name
 126
 127      @return a KeyStore repesenting the desired type
 128
 129      @throws KeyStoreException if the type of keystore is not
 130               implemented by the given provider
 131      @throws NoSuchProviderException if the provider is not found
 132      @throws IllegalArgumentException if the provider string is
 133                null or empty
 134    */
 135   public static KeyStore getInstance(String type, String provider)
 136     throws KeyStoreException, NoSuchProviderException
 137   {
 138     if (provider == null || provider.length() == 0)
 139       throw new IllegalArgumentException("Illegal provider");
 140     Provider p = Security.getProvider(provider);
 141     if (p == null)
 142       throw new NoSuchProviderException();
 143
 144     return getInstance(p.getProperty("KeyStore." + type), type, p);
 145   }
 146
 147   /**
 148      Gets an instance of the KeyStore class representing
 149      the specified key store from the specified provider.
 150      If the type is not found then, it throws KeyStoreException.
 151      If the provider is not found, then it throws
 152      NoSuchProviderException.
 153
 154      @param type the type of keystore to choose
 155      @param provider the keystore provider
 156
 157      @return a KeyStore repesenting the desired type
 158
 159      @throws KeyStoreException if the type of keystore is not
 160               implemented by the given provider
 161      @throws IllegalArgumentException if the provider object is null
 162      @since 1.4
 163    */
 164   public static KeyStore getInstance(String type, Provider provider)
 165     throws KeyStoreException
 166   {
 167     if (provider == null)
 168       throw new IllegalArgumentException("Illegal provider");
 169
 170     return getInstance(provider.getProperty("KeyStore." + type),
 171                        type, provider);
 172   }
 173
 174   private static KeyStore getInstance(String classname,
 175                                       String type,
 176                                       Provider provider)
 177     throws KeyStoreException
 178   {
 179     try
 180       {
 181         return new KeyStore((KeyStoreSpi) Class.forName(classname).
 182                             newInstance(), provider, type);
 183       }
 184     catch (ClassNotFoundException cnfe)
 185       {
 186         throw new KeyStoreException("Class not found");
 187       }
 188     catch (InstantiationException ie)
 189       {
 190         throw new KeyStoreException("Class instantiation failed");
 191       }
 192     catch (IllegalAccessException iae)
 193       {
 194         throw new KeyStoreException("Illegal Access");
 195       }
 196   }
 197
 198
 199   /**
 200      Gets the provider that the class is from.
 201
 202      @return the provider of this class
 203    */
 204   public final Provider getProvider()
 205   {
 206     return provider;
 207   }
 208
 209   /**
 210      Returns the type of the KeyStore supported
 211
 212      @return A string with the type of KeyStore
 213    */
 214   public final String getType()
 215   {
 216     return type;
 217   }
 218
 219   /**
 220      Returns the key associated with given alias using the
 221      supplied password.
 222
 223      @param alias an alias for the key to get
 224      @param password password to access key with
 225
 226      @return the requested key, or null otherwise
 227
 228      @throws NoSuchAlgorithmException if there is no algorithm
 229      for recovering the key
 230      @throws UnrecoverableKeyException key cannot be reocovered
 231      (wrong password).
 232    */
 233   public final Key getKey(String alias, char[]password)
 234     throws KeyStoreException, NoSuchAlgorithmException,
 235     UnrecoverableKeyException
 236   {
 237     return keyStoreSpi.engineGetKey(alias, password);
 238   }
 239
 240   /**
 241      Gets a Certificate chain for the specified alias.
 242
 243      @param alias the alias name
 244
 245      @return a chain of Certificates ( ordered from the user's
 246      certificate to the Certificate Authority's ) or
 247      null if the alias does not exist or there is no
 248      certificate chain for the alias ( the alias refers
 249      to a trusted certificate entry or there is no entry).
 250    */
 251   public final java.security.cert.
 252     Certificate[] getCertificateChain(String alias) throws KeyStoreException
 253   {
 254     return keyStoreSpi.engineGetCertificateChain(alias);
 255   }
 256
 257   /**
 258      Gets a Certificate for the specified alias.
 259
 260      If there is a trusted certificate entry then that is returned.
 261      it there is a key entry with a certificate chain then the
 262      first certificate is return or else null.
 263
 264      @param alias the alias name
 265
 266      @return a Certificate or null if the alias does not exist
 267      or there is no certificate for the alias
 268    */
 269   public final java.security.cert.Certificate getCertificate(String alias)
 270     throws KeyStoreException
 271   {
 272     return keyStoreSpi.engineGetCertificate(alias);
 273   }
 274
 275   /**
 276      Gets entry creation date for the specified alias.
 277
 278      @param alias the alias name
 279
 280      @returns the entry creation date or null
 281    */
 282   public final Date getCreationDate(String alias) throws KeyStoreException
 283   {
 284     return keyStoreSpi.engineGetCreationDate(alias);
 285   }
 286
 287   /**
 288      Assign the key to the alias in the keystore, protecting it
 289      with the given password. It will overwrite an existing
 290      entry and if the key is a PrivateKey, also add the
 291      certificate chain representing the corresponding public key.
 292
 293      @param alias the alias name
 294      @param key the key to add
 295      @password the password to protect with
 296      @param chain the certificate chain for the corresponding
 297      public key
 298
 299      @throws KeyStoreException if it fails
 300    */
 301   public final void setKeyEntry(String alias, Key key, char[]password,
 302                                 java.security.cert.
 303                                 Certificate[]chain) throws KeyStoreException
 304   {
 305     keyStoreSpi.engineSetKeyEntry(alias, key, password, chain);
 306   }
 307
 308   /**
 309      Assign the key to the alias in the keystore. It will overwrite
 310      an existing entry and if the key is a PrivateKey, also
 311      add the certificate chain representing the corresponding
 312      public key.
 313
 314      @param alias the alias name
 315      @param key the key to add
 316      @param chain the certificate chain for the corresponding
 317      public key
 318
 319      @throws KeyStoreException if it fails
 320    */
 321   public final void setKeyEntry(String alias, byte[]key,
 322                                 java.security.cert.
 323                                 Certificate[]chain) throws KeyStoreException
 324   {
 325     keyStoreSpi.engineSetKeyEntry(alias, key, chain);
 326   }
 327
 328   /**
 329      Assign the certificate to the alias in the keystore. It
 330      will overwrite an existing entry.
 331
 332      @param alias the alias name
 333      @param cert the certificate to add
 334
 335      @throws KeyStoreException if it fails
 336    */
 337   public final void setCertificateEntry(String alias,
 338                                         java.security.cert.
 339                                         Certificate cert) throws
 340     KeyStoreException
 341   {
 342     keyStoreSpi.engineSetCertificateEntry(alias, cert);
 343   }
 344
 345   /**
 346      Deletes the entry for the specified entry.
 347
 348      @param alias the alias name
 349
 350      @throws KeyStoreException if it fails
 351    */
 352   public final void deleteEntry(String alias) throws KeyStoreException
 353   {
 354     keyStoreSpi.engineDeleteEntry(alias);
 355   }
 356
 357   /**
 358      Generates a list of all the aliases in the keystore.
 359
 360      @return an Enumeration of the aliases
 361    */
 362   public final Enumeration aliases() throws KeyStoreException
 363   {
 364     return keyStoreSpi.engineAliases();
 365   }
 366
 367   /**
 368      Determines if the keystore contains the specified alias.
 369
 370      @param alias the alias name
 371
 372      @return true if it contains the alias, false otherwise
 373    */
 374   public final boolean containsAlias(String alias) throws KeyStoreException
 375   {
 376     return keyStoreSpi.engineContainsAlias(alias);
 377   }
 378
 379   /**
 380      Returns the number of entries in the keystore.
 381
 382      @returns the number of keystore entries.
 383    */
 384   public final int size() throws KeyStoreException
 385   {
 386     return keyStoreSpi.engineSize();
 387   }
 388
 389   /**
 390      Determines if the keystore contains a key entry for
 391      the specified alias.
 392
 393      @param alias the alias name
 394
 395      @return true if it is a key entry, false otherwise
 396    */
 397   public final boolean isKeyEntry(String alias) throws KeyStoreException
 398   {
 399     return keyStoreSpi.engineIsKeyEntry(alias);
 400   }
 401
 402
 403   /**
 404      Determines if the keystore contains a certificate entry for
 405      the specified alias.
 406
 407      @param alias the alias name
 408
 409      @return true if it is a certificate entry, false otherwise
 410    */
 411   public final boolean isCertificateEntry(String alias)
 412     throws KeyStoreException
 413   {
 414     return keyStoreSpi.engineIsCertificateEntry(alias);
 415   }
 416
 417   /**
 418      Determines if the keystore contains the specified certificate
 419      entry and returns the alias.
 420
 421      It checks every entry and for a key entry checks only the
 422      first certificate in the chain.
 423
 424      @param cert Certificate to look for
 425
 426      @return alias of first matching certificate, null if it
 427      does not exist.
 428    */
 429   public final String getCertificateAlias(java.security.cert.Certificate cert)
 430     throws KeyStoreException
 431   {
 432     return keyStoreSpi.engineGetCertificateAlias(cert);
 433   }
 434
 435   /**
 436      Stores the keystore in the specified output stream and it
 437      uses the specified key it keep it secure.
 438
 439      @param stream the output stream to save the keystore to
 440      @param password the password to protect the keystore integrity with
 441
 442      @throws IOException if an I/O error occurs.
 443      @throws NoSuchAlgorithmException the data integrity algorithm
 444      used cannot be found.
 445      @throws CertificateException if any certificates could not be
 446      stored in the output stream.
 447    */
 448   public final void store(OutputStream stream, char[]password)
 449     throws KeyStoreException, IOException, NoSuchAlgorithmException,
 450     CertificateException
 451   {
 452     keyStoreSpi.engineStore(stream, password);
 453   }
 454
 455   /**
 456      Loads the keystore from the specified input stream and it
 457      uses the specified password to check for integrity if supplied.
 458
 459      @param stream the input stream to load the keystore from
 460      @param password the password to check the keystore integrity with
 461
 462      @throws IOException if an I/O error occurs.
 463      @throws NoSuchAlgorithmException the data integrity algorithm
 464      used cannot be found.
 465      @throws CertificateException if any certificates could not be
 466      stored in the output stream.
 467    */
 468   public final void load(InputStream stream, char[]password)
 469     throws IOException, NoSuchAlgorithmException, CertificateException
 470   {
 471     keyStoreSpi.engineLoad(stream, password);
 472   }
 473
 474   /**
 475      Returns the default KeyStore type. This method looks up the
 476      type in <JAVA_HOME>/lib/security/java.security with the
 477      property "keystore.type" or if that fails then "jks" .
 478    */
 479   public static final String getDefaultType()
 480   {
 481     String tmp;
 482     //Security reads every property in java.security so it
 483     //will return this property if it exists.
 484     tmp = Security.getProperty("keystore.type");
 485
 486     if (tmp == null)
 487       tmp = "jks";
 488
 489     return tmp;
 490   }
 491 }