sdk/sources/android-25/java/security/SignedObject.java

   1 /*
   2  * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25
  26 package java.security;
  27
  28 import java.io.*;
  29
  30 /**
  31  * <p> SignedObject is a class for the purpose of creating authentic
  32  * runtime objects whose integrity cannot be compromised without being
  33  * detected.
  34  *
  35  * <p> More specifically, a SignedObject contains another Serializable
  36  * object, the (to-be-)signed object and its signature.
  37  *
  38  * <p> The signed object is a "deep copy" (in serialized form) of an
  39  * original object.  Once the copy is made, further manipulation of
  40  * the original object has no side effect on the copy.
  41  *
  42  * <p> The underlying signing algorithm is designated by the Signature
  43  * object passed to the constructor and the <code>verify</code> method.
  44  * A typical usage for signing is the following:
  45  *
  46  * <p> <code> <pre>
  47  * Signature signingEngine = Signature.getInstance(algorithm,
  48  *                                                 provider);
  49  * SignedObject so = new SignedObject(myobject, signingKey,
  50  *                                    signingEngine);
  51  * </pre> </code>
  52  *
  53  * <p> A typical usage for verification is the following (having
  54  * received SignedObject <code>so</code>):
  55  *
  56  * <p> <code> <pre>
  57  * Signature verificationEngine =
  58  *     Signature.getInstance(algorithm, provider);
  59  * if (so.verify(publickey, verificationEngine))
  60  *     try {
  61  *         Object myobj = so.getObject();
  62  *     } catch (java.lang.ClassNotFoundException e) {};
  63  * </pre> </code>
  64  *
  65  * <p> Several points are worth noting.  First, there is no need to
  66  * initialize the signing or verification engine, as it will be
  67  * re-initialized inside the constructor and the <code>verify</code>
  68  * method. Secondly, for verification to succeed, the specified
  69  * public key must be the public key corresponding to the private key
  70  * used to generate the SignedObject.
  71  *
  72  * <p> More importantly, for flexibility reasons, the
  73  * constructor and <code>verify</code> method allow for
  74  * customized signature engines, which can implement signature
  75  * algorithms that are not installed formally as part of a crypto
  76  * provider.  However, it is crucial that the programmer writing the
  77  * verifier code be aware what <code>Signature</code> engine is being
  78  * used, as its own implementation of the <code>verify</code> method
  79  * is invoked to verify a signature.  In other words, a malicious
  80  * <code>Signature</code> may choose to always return true on
  81  * verification in an attempt to bypass a security check.
  82  *
  83  * <p> The signature algorithm can be, among others, the NIST standard
  84  * DSA, using DSA and SHA-1.  The algorithm is specified using the
  85  * same convention as that for signatures. The DSA algorithm using the
  86  * SHA-1 message digest algorithm can be specified, for example, as
  87  * "SHA/DSA" or "SHA-1/DSA" (they are equivalent).  In the case of
  88  * RSA, there are multiple choices for the message digest algorithm,
  89  * so the signing algorithm could be specified as, for example,
  90  * "MD2/RSA", "MD5/RSA" or "SHA-1/RSA".  The algorithm name must be
  91  * specified, as there is no default.
  92  *
  93  * <p> The name of the Cryptography Package Provider is designated
  94  * also by the Signature parameter to the constructor and the
  95  * <code>verify</code> method.  If the provider is not
  96  * specified, the default provider is used.  Each installation can
  97  * be configured to use a particular provider as default.
  98  *
  99  * <p> Potential applications of SignedObject include:
 100  * <ul>
 101  * <li> It can be used
 102  * internally to any Java runtime as an unforgeable authorization
 103  * token -- one that can be passed around without the fear that the
 104  * token can be maliciously modified without being detected.
 105  * <li> It
 106  * can be used to sign and serialize data/object for storage outside
 107  * the Java runtime (e.g., storing critical access control data on
 108  * disk).
 109  * <li> Nested SignedObjects can be used to construct a logical
 110  * sequence of signatures, resembling a chain of authorization and
 111  * delegation.
 112  * </ul>
 113  *
 114  * @see Signature
 115  *
 116  * @author Li Gong
 117  */
 118
 119 public final class SignedObject implements Serializable {
 120
 121     private static final long serialVersionUID = 720502720485447167L;
 122
 123     /*
 124      * The original content is "deep copied" in its serialized format
 125      * and stored in a byte array.  The signature field is also in the
 126      * form of byte array.
 127      */
 128
 129     private byte[] content;
 130     private byte[] signature;
 131     private String thealgorithm;
 132
 133     /**
 134      * Constructs a SignedObject from any Serializable object.
 135      * The given object is signed with the given signing key, using the
 136      * designated signature engine.
 137      *
 138      * @param object the object to be signed.
 139      * @param signingKey the private key for signing.
 140      * @param signingEngine the signature signing engine.
 141      *
 142      * @exception IOException if an error occurs during serialization
 143      * @exception InvalidKeyException if the key is invalid.
 144      * @exception SignatureException if signing fails.
 145      */
 146     public SignedObject(Serializable object, PrivateKey signingKey,
 147                         Signature signingEngine)
 148         throws IOException, InvalidKeyException, SignatureException {
 149             // creating a stream pipe-line, from a to b
 150             ByteArrayOutputStream b = new ByteArrayOutputStream();
 151             ObjectOutput a = new ObjectOutputStream(b);
 152
 153             // write and flush the object content to byte array
 154             a.writeObject(object);
 155             a.flush();
 156             a.close();
 157             this.content = b.toByteArray();
 158             b.close();
 159
 160             // now sign the encapsulated object
 161             this.sign(signingKey, signingEngine);
 162     }
 163
 164     /**
 165      * Retrieves the encapsulated object.
 166      * The encapsulated object is de-serialized before it is returned.
 167      *
 168      * @return the encapsulated object.
 169      *
 170      * @exception IOException if an error occurs during de-serialization
 171      * @exception ClassNotFoundException if an error occurs during
 172      * de-serialization
 173      */
 174     public Object getObject()
 175         throws IOException, ClassNotFoundException
 176     {
 177         // creating a stream pipe-line, from b to a
 178         ByteArrayInputStream b = new ByteArrayInputStream(this.content);
 179         ObjectInput a = new ObjectInputStream(b);
 180         Object obj = a.readObject();
 181         b.close();
 182         a.close();
 183         return obj;
 184     }
 185
 186     /**
 187      * Retrieves the signature on the signed object, in the form of a
 188      * byte array.
 189      *
 190      * @return the signature. Returns a new array each time this
 191      * method is called.
 192      */
 193     public byte[] getSignature() {
 194         return this.signature.clone();
 195     }
 196
 197     /**
 198      * Retrieves the name of the signature algorithm.
 199      *
 200      * @return the signature algorithm name.
 201      */
 202     public String getAlgorithm() {
 203         return this.thealgorithm;
 204     }
 205
 206     /**
 207      * Verifies that the signature in this SignedObject is the valid
 208      * signature for the object stored inside, with the given
 209      * verification key, using the designated verification engine.
 210      *
 211      * @param verificationKey the public key for verification.
 212      * @param verificationEngine the signature verification engine.
 213      *
 214      * @exception SignatureException if signature verification failed.
 215      * @exception InvalidKeyException if the verification key is invalid.
 216      *
 217      * @return <tt>true</tt> if the signature
 218      * is valid, <tt>false</tt> otherwise
 219      */
 220     public boolean verify(PublicKey verificationKey,
 221                           Signature verificationEngine)
 222          throws InvalidKeyException, SignatureException {
 223              verificationEngine.initVerify(verificationKey);
 224              verificationEngine.update(this.content.clone());
 225              return verificationEngine.verify(this.signature.clone());
 226     }
 227
 228     /*
 229      * Signs the encapsulated object with the given signing key, using the
 230      * designated signature engine.
 231      *
 232      * @param signingKey the private key for signing.
 233      * @param signingEngine the signature signing engine.
 234      *
 235      * @exception InvalidKeyException if the key is invalid.
 236      * @exception SignatureException if signing fails.
 237      */
 238     private void sign(PrivateKey signingKey, Signature signingEngine)
 239         throws InvalidKeyException, SignatureException {
 240             // initialize the signing engine
 241             signingEngine.initSign(signingKey);
 242             signingEngine.update(this.content.clone());
 243             this.signature = signingEngine.sign().clone();
 244             this.thealgorithm = signingEngine.getAlgorithm();
 245     }
 246
 247     /**
 248      * readObject is called to restore the state of the SignedObject from
 249      * a stream.
 250      */
 251     private void readObject(java.io.ObjectInputStream s)
 252         throws java.io.IOException, ClassNotFoundException {
 253             java.io.ObjectInputStream.GetField fields = s.readFields();
 254             content = ((byte[])fields.get("content", null)).clone();
 255             signature = ((byte[])fields.get("signature", null)).clone();
 256             thealgorithm = (String)fields.get("thealgorithm", null);
 257     }
 258 }