SealedObject


1   /*
2    * @(#)SealedObject.java    1.6 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7     
8   /*
9    * NOTE:
10   * Because of various external restrictions (i.e. US export
11   * regulations, etc.), the actual source code can not be provided
12   * at this time. This file represents the skeleton of the source
13   * file, so that javadocs of the API can be created.
14   */
15  
16  package javax.crypto;
17  
18  import java.io.*;
19  
20  import java.security.AlgorithmParameters;
21  import java.security.Key;
22  import java.security.InvalidKeyException;
23  import java.security.InvalidAlgorithmParameterException;
24  import java.security.NoSuchAlgorithmException;
25  import java.security.NoSuchProviderException;
26  
27  /** 
28   * This class enables a programmer to create an object and protect its
29   * confidentiality with a cryptographic algorithm.
30   *
31   * <p> Given any Serializable object, one can create a SealedObject
32   * that encapsulates the original object, in serialized
33   * format (i.e., a "deep copy"), and seals (encrypts) its serialized contents,
34   * using a cryptographic algorithm such as DES, to protect its
35   * confidentiality.  The encrypted content can later be decrypted (with
36   * the corresponding algorithm using the correct decryption key) and
37   * de-serialized, yielding the original object.
38   *
39   * <p> Note that the Cipher object must be fully initialized with the
40   * correct algorithm, key, padding scheme, etc., before being applied
41   * to a SealedObject.
42   *
43   * <p> The original object that was sealed can be recovered in two different
44   * ways: <p>
45   *
46   * <ul>
47   *
48   * <li>by using the {@link #getObject(javax.crypto.Cipher) getObject}
49   * method that takes a <code>Cipher</code> object.
50   * 
51   * <p> This method requires a fully initialized <code>Cipher</code> object,
52   * initialized with the
53   * exact same algorithm, key, padding scheme, etc., that were used to seal the
54   * object.
55   *
56   * <p> This approach has the advantage that the party who unseals the
57   * sealed object does not require knowledge of the decryption key. For example,
58   * after one party has initialized the cipher object with the required
59   * decryption key, it could hand over the cipher object to
60   * another party who then unseals the sealed object.
61   *
62   * <p>
63   * 
64   * <li>by using one of the
65   * {@link #getObject(java.security.Key) getObject} methods
66   * that take a <code>Key</code> object.
67   *
68   * <p> In this approach, the <code>getObject</code> method creates a cipher
69   * object for the appropriate decryption algorithm and initializes it with the
70   * given decryption key and the algorithm parameters (if any) that were stored
71   * in the sealed object.
72   *
73   * <p> This approach has the advantage that the party who
74   * unseals the object does not need to keep track of the parameters (e.g., an
75   * IV) that were used to seal the object.
76   *
77   * </ul>
78   *
79   * @author Li Gong
80   * @author Jan Luehe
81   * @version     1.30, 10/29/03
82   * @see Cipher
83   * @since 1.4
84   */
85  public class SealedObject implements Serializable
86  {
87      /** 
88       * The encoded parameters.
89       *
90       * @serial
91       */
92      protected byte[] encodedParams;
93  
94      /** 
95       * The serialized object contents in encrypted format.
96       *
97       * @serial
98       */
99      private byte[] encryptedContent;
100 
101     /** 
102      * The algorithm that was used to seal this object.
103      *
104      * @serial
105      */
106     private String sealAlg;
107 
108     /** 
109      * The algorithm of the parameters used.
110      *
111      * @serial
112      */
113     private String paramsAlg;
114 
115     /** 
116      * Constructs a SealedObject from any Serializable object.
117      *
118      * <p>The given object is serialized, and its serialized contents are
119      * encrypted using the given Cipher, which must be fully initialized.
120      *
121      * <p>Any algorithm parameters that may be used in the encryption
122      * operation are stored inside of the new <code>SealedObject</code>.
123      *
124      * @param object the object to be sealed; can be null.
125      * @param c the cipher used to seal the object.
126      *
127      * @exception NullPointerException if the given cipher is null.
128      * @exception IOException if an error occurs during serialization
129      * @exception IllegalBlockSizeException if the given cipher is a block
130      * cipher, no padding has been requested, and the total input length
131      * (i.e., the length of the serialized object contents) is not a multiple
132      * of the cipher's block size
133      */
134     public SealedObject(Serializable object, Cipher c)
135         throws IOException, IllegalBlockSizeException
136     { }
137 
138     /** 
139      * Constructs a SealedObject object from the passed-in SealedObject.
140      *
141      * @param so a SealedObject object
142      * @exception NullPointerException if the given sealed object is null.
143      */
144     protected SealedObject(SealedObject so) { }
145 
146     /** 
147      * Returns the algorithm that was used to seal this object.
148      *
149      * @return the algorithm that was used to seal this object.
150      */
151     public final String getAlgorithm() { }
152 
153     /** 
154      * Retrieves the original (encapsulated) object.
155      *
156      * <p>This method creates a cipher for the algorithm that had been used in
157      * the sealing operation.
158      * If the default provider package provides an implementation of that
159      * algorithm, an instance of Cipher containing that implementation is used.
160      * If the algorithm is not available in the default package, other
161      * packages are searched.
162      * The Cipher object is initialized for decryption, using the given
163      * <code>key</code> and the parameters (if any) that had been used in the
164      * sealing operation.
165      *
166      * <p>The encapsulated object is unsealed and de-serialized, before it is
167      * returned.
168      *
169      * @param key the key used to unseal the object.
170      *
171      * @return the original object.
172      *
173      * @exception IOException if an error occurs during de-serialiazation.
174      * @exception ClassNotFoundException if an error occurs during 
175      * de-serialiazation.
176      * @exception NoSuchAlgorithmException if the algorithm to unseal the
177      * object is not available.
178      * @exception InvalidKeyException if the given key cannot be used to unseal
179      * the object (e.g., it has the wrong algorithm).
180      */
181     public final Object getObject(Key key)
182         throws IOException, ClassNotFoundException, NoSuchAlgorithmException,
183         InvalidKeyException
184     { }
185 
186     /** 
187      * Retrieves the original (encapsulated) object.
188      *
189      * <p>The encapsulated object is unsealed (using the given Cipher,
190      * assuming that the Cipher is already properly initialized) and
191      * de-serialized, before it is returned.
192      *
193      * @param c the cipher used to unseal the object
194      *
195      * @return the original object.
196      *
197      * @exception NullPointerException if the given cipher is null.
198      * @exception IOException if an error occurs during de-serialiazation
199      * @exception ClassNotFoundException if an error occurs during 
200      * de-serialiazation
201      * @exception IllegalBlockSizeException if the given cipher is a block
202      * cipher, no padding has been requested, and the total input length is
203      * not a multiple of the cipher's block size
204      * @exception BadPaddingException if the given cipher has been 
205      * initialized for decryption, and padding has been specified, but
206      * the input data does not have proper expected padding bytes
207      */
208     public final Object getObject(Cipher c)
209         throws IOException, ClassNotFoundException, IllegalBlockSizeException,
210         BadPaddingException
211     { }
212 
213     /** 
214      * Retrieves the original (encapsulated) object.
215      *
216      * <p>This method creates a cipher for the algorithm that had been used in
217      * the sealing operation, using an implementation of that algorithm from
218      * the given <code>provider</code>.
219      * The Cipher object is initialized for decryption, using the given
220      * <code>key</code> and the parameters (if any) that had been used in the
221      * sealing operation.
222      *
223      * <p>The encapsulated object is unsealed and de-serialized, before it is
224      * returned.
225      *
226      * @param key the key used to unseal the object.
227      * @param provider the name of the provider of the algorithm to unseal
228      * the object.
229      *
230      * @return the original object.
231      *
232      * @exception IllegalArgumentException if the given provider is null
233      * or empty.
234      * @exception IOException if an error occurs during de-serialiazation.
235      * @exception ClassNotFoundException if an error occurs during 
236      * de-serialiazation.
237      * @exception NoSuchAlgorithmException if the algorithm to unseal the
238      * object is not available.
239      * @exception NoSuchProviderException if the given provider is not
240      * configured.
241      * @exception InvalidKeyException if the given key cannot be used to unseal
242      * the object (e.g., it has the wrong algorithm).
243      */
244     public final Object getObject(Key key, String provider)
245         throws IOException, ClassNotFoundException, NoSuchAlgorithmException,
246         NoSuchProviderException, InvalidKeyException
247     { }
248 
249     /** 
250      * Restores the state of the SealedObject from a stream.
251      * @param s the object input stream.
252      * @exception NullPointerException if s is null.
253      */
254     private void readObject(ObjectInputStream s)
255         throws IOException, ClassNotFoundException
256     { }
257 }
258
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Java Books Remove Frame
Popular Tags