Source for gnu.javax.crypto.keyring.IKeyring

   1: /* IKeyring.java --
   2:    Copyright (C) 2003, 2006 Free Software Foundation, Inc.
   3: 
   4: This file is a 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 of the License, or (at
   9: your option) 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; if not, write to the Free Software
  18: Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
  19: 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: 
  39: package gnu.javax.crypto.keyring;
  40: 
  41: import java.io.IOException;
  42: import java.util.Enumeration;
  43: import java.util.List;
  44: import java.util.Map;
  45: 
  46: /**
  47:  * The top-level interface to a <i>keyring:</i> a file that is used to store
  48:  * and protect public and private cryptographic keys.
  49:  * <p>
  50:  * A <i>keyring</i> is modelled as a mapping of one <i>alias</i> to one or
  51:  * more <i>entries</i> (optionally of different types).
  52:  * <p>
  53:  * See also the sub-interfaces {@link IPublicKeyring} and
  54:  * {@link IPrivateKeyring} for special types of <i>keyrings</i> --the
  55:  * difference being in the type of entries they contain.
  56:  */
  57: public interface IKeyring
  58: {
  59:   /**
  60:    * Property name for the source of data to load the keyring from. The value
  61:    * mapped must be a {@link java.io.InputStream}.
  62:    */
  63:   public static final String KEYRING_DATA_IN = "gnu.crypto.keyring.data.in";
  64: 
  65:   /**
  66:    * Property name for the data sink to store the keyring to. The value mapped
  67:    * must be a {@link java.io.OutputStream}.
  68:    */
  69:   public static final String KEYRING_DATA_OUT = "gun.crypto.keyring.data.out";
  70: 
  71:   /**
  72:    * Property name for the keyring's top-level password, used to authenticate
  73:    * and/or transform the store itself. The mapped value must be a char array.
  74:    */
  75:   public static final String KEYRING_PASSWORD = "gnu.crypto.keyring.password";
  76: 
  77:   /**
  78:    * Loads a keyring into memory.
  79:    * <p>
  80:    * What happens to the current contents of this keyring? are the new ones
  81:    * merged with the current ones or do they simply replace them?
  82:    *
  83:    * @param attributes The attributes that designate the source where the store
  84:    *          is to be loaded from. What happens
  85:    * @throws IllegalArgumentException If the attributes are inappropriate.
  86:    * @throws IOException If the keyring file cannot be read.
  87:    * @throws SecurityException If the given password is incorrect, or if the
  88:    *           top-level authentication or decryption fails.
  89:    */
  90:   void load(Map attributes) throws IOException;
  91: 
  92:   /**
  93:    * Stores the contents of this keyring to persistent storage as specified by
  94:    * the designated <code>attributes</code>.
  95:    *
  96:    * @param attributes the attributes that define where the contents of this
  97:    *          keyring will be stored.
  98:    * @throws IOException if an exception occurs during the process.
  99:    */
 100:   void store(Map attributes) throws IOException;
 101: 
 102:   /**
 103:    * Resets this keyring, clearing all sensitive data. This method always
 104:    * suceeds.
 105:    */
 106:   void reset();
 107: 
 108:   /**
 109:    * Returns the number of entries in this keyring.
 110:    *
 111:    * @return The number of current entries in this keyring.
 112:    */
 113:   int size();
 114: 
 115:   /**
 116:    * Returns an {@link Enumeration} of all aliases (instances of {@link String})
 117:    * in this keyring.
 118:    *
 119:    * @return The enumeration of {@link String}s each representing an <i>alias</i>
 120:    *         found in this keyring.
 121:    */
 122:   Enumeration aliases();
 123: 
 124:   /**
 125:    * Tests whether or not this keyring contains the given alias.
 126:    *
 127:    * @param alias The alias to check.
 128:    * @return true if this keyring contains the alias.
 129:    */
 130:   boolean containsAlias(String alias);
 131: 
 132:   /**
 133:    * Returns a {@link List} of entries (instances of {@link Entry}) for the
 134:    * given <code>alias</code>, or <code>null</code> if there no such entry
 135:    * exists.
 136:    *
 137:    * @param alias The alias of the entry(ies) to return.
 138:    * @return A list of all entries (instances of {@link Entry} that have the
 139:    *         given <code>alias</code>, or <code>null</code> if no one
 140:    *         {@link Entry} can be found with the designated <code>alias</code>.
 141:    */
 142:   List get(String alias);
 143: 
 144:   /**
 145:    * Adds a designated {@link Entry} to this keyring.
 146:    * <p>
 147:    * What happens if there is already an entry with the same alias?
 148:    *
 149:    * @param entry The entry to put in this keyring.
 150:    */
 151:   void add(Entry entry);
 152: 
 153:   /**
 154:    * Removes an entry with the designated <code>alias</code> from this
 155:    * keyring. Does nothing if there was no such entry.
 156:    * <p>
 157:    * What happens if there are more than one?
 158:    *
 159:    * @param alias The alias of the entry to remove.
 160:    */
 161:   void remove(String alias);
 162: }