Imported GNU Classpath 0.90
[official-gcc.git] / libjava / classpath / gnu / javax / crypto / keyring / IKeyring.java
blob56f467df26eb613d919d9042f31a4cd67bc8229f
1 /* IKeyring.java --
2 Copyright (C) 2003, 2006 Free Software Foundation, Inc.
4 This file is a part of GNU Classpath.
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.
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.
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
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.
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. */
39 package gnu.javax.crypto.keyring;
41 import java.io.IOException;
42 import java.util.Enumeration;
43 import java.util.List;
44 import java.util.Map;
46 /**
47 * <p>The top-level interface to a <i>keyring:</i> a file that is used to
48 * store and protect public and private cryptographic keys.</p>
50 * <p>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).</p>
53 * <p>See also the sub-interfaces {@link IPublicKeyring} and
54 * {@link IPrivateKeyring} for special types of <i>keyrings</i> --the difference
55 * being in the type of entries they contain.</p>
57 public interface IKeyring
60 /**
61 * <p>Property name for the source of data to load the keyring from. The
62 * value mapped must be a {@link java.io.InputStream}.</p>
64 public static final String KEYRING_DATA_IN = "gnu.crypto.keyring.data.in";
66 /**
67 * <p>Property name for the data sink to store the keyring to. The value
68 * mapped must be a {@link java.io.OutputStream}.</p>
70 public static final String KEYRING_DATA_OUT = "gun.crypto.keyring.data.out";
72 /**
73 * <p>Property name for the keyring's top-level password, used to
74 * authenticate and/or transform the store itself. The mapped value must be a
75 * char array.</p>
77 public static final String KEYRING_PASSWORD = "gnu.crypto.keyring.password";
79 /**
80 * <p>Loads a keyring into memory.</p>
82 * <p>What happens to the current contents of this keyring? are the new ones
83 * merged with the current ones or do they simply replace them?</p>
85 * @param attributes The attributes that designate the source where the store
86 * is to be loaded from. What happens
87 * @throws IllegalArgumentException If the attributes are inappropriate.
88 * @throws IOException If the keyring file cannot be read.
89 * @throws SecurityException If the given password is incorrect, or if the
90 * top-level authentication or decryption fails.
92 void load(Map attributes) throws IOException;
94 /**
95 * <p>Stores the contents of this keyring to persistent storage as specified
96 * by the designated <code>attributes</code>.</p>
98 * @param attributes the attributes that define where the contents of this
99 * keyring will be stored.
100 * @throws IOException if an exception occurs during the process.
102 void store(Map attributes) throws IOException;
105 * <p>Resets this keyring, clearing all sensitive data. This method always
106 * suceeds.</p>
108 void reset();
111 * <p>Returns the number of entries in this keyring.</p>
113 * @return The number of current entries in this keyring.
115 int size();
118 * <p>Returns an {@link Enumeration} of all aliases (instances of
119 * {@link String}) in this keyring.</p>
121 * @return The enumeration of {@link String}s each representing an
122 * <i>alias</i> found in this keyring.
124 Enumeration aliases();
127 * Tests whether or not this keyring contains the given alias.
129 * @param alias The alias to check.
130 * @return true if this keyring contains the alias.
132 boolean containsAlias(String alias);
135 * <p>Returns a {@link List} of entries (instances of {@link Entry}) for the
136 * given <code>alias</code>, or <code>null</code> if there no such entry
137 * exists.</p>
139 * @param alias The alias of the entry(ies) to return.
140 * @return A list of all entries (instances of {@link Entry} that have the
141 * given <code>alias</code>, or <code>null</code> if no one {@link Entry} can
142 * be found with the designated <code>alias</code>.
144 List get(String alias);
147 * <p>Adds a designated {@link Entry} to this keyring.</p>
149 * <p>What happens if there is already an entry with the same alias?</p>
151 * @param entry The entry to put in this keyring.
153 void add(Entry entry);
156 * <p>Removes an entry with the designated <code>alias</code> from this
157 * keyring. Does nothing if there was no such entry.</p>
159 * <p>What happens if there are more than one?</p>
161 * @param alias The alias of the entry to remove.
163 void remove(String alias);