      1 /*
      2  * Copyright (c) 1997, 2019, 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} method.
     44  * A typical usage for signing is the following:
     45  *
     46  * <pre>{@code
     47  * Signature signingEngine = Signature.getInstance(algorithm,
     48  *                                                 provider);
     49  * SignedObject so = new SignedObject(myobject, signingKey,
     50  *                                    signingEngine);
     51  * }</pre>
     52  *
     53  * <p> A typical usage for verification is the following (having
     54  * received SignedObject {@code so}):
     55  *
     56  * <pre>{@code
     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>
     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}
     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} 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} engine is being
     78  * used, as its own implementation of the {@code verify} method
     79  * is invoked to verify a signature.  In other words, a malicious
     80  * {@code Signature} 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-256.  The algorithm is specified using the
     85  * same convention as that for signatures. The DSA algorithm using the
     86  * SHA-256 message digest algorithm can be specified, for example, as
     87  * "SHA256withDSA".  In the case of
     88  * RSA the signing algorithm could be specified as, for example,
     89  * "SHA256withRSA".  The algorithm name must be
     90  * specified, as there is no default.
     91  *
     92  * <p> The name of the Cryptography Package Provider is designated
     93  * also by the Signature parameter to the constructor and the
     94  * {@code verify} method.  If the provider is not
     95  * specified, the default provider is used.  Each installation can
     96  * be configured to use a particular provider as default.
     97  *
     98  * <p> Potential applications of SignedObject include:
     99  * <ul>
    100  * <li> It can be used
    101  * internally to any Java runtime as an unforgeable authorization
    102  * token -- one that can be passed around without the fear that the
    103  * token can be maliciously modified without being detected.
    104  * <li> It
    105  * can be used to sign and serialize data/object for storage outside
    106  * the Java runtime (e.g., storing critical access control data on
    107  * disk).
    108  * <li> Nested SignedObjects can be used to construct a logical
    109  * sequence of signatures, resembling a chain of authorization and
    110  * delegation.
    111  * </ul>
    112  *
    113  * @see Signature
    114  *
    115  * @author Li Gong
    116  * @since 1.2
    117  */
    118
    119 public final class SignedObject implements Serializable {
    120
    121     @java.io.Serial
    122     private static final long serialVersionUID = 720502720485447167L;
    123
    124     /*
    125      * The original content is "deep copied" in its serialized format
    126      * and stored in a byte array.  The signature field is also in the
    127      * form of byte array.
    128      */
    129
    130     private byte[] content;

    131     private byte[] signature;

    132     private String thealgorithm;
    133
    134     /**
    135      * Constructs a SignedObject from any Serializable object.
    136      * The given object is signed with the given signing key, using the
    137      * designated signature engine.
    138      *
    139      * @param object the object to be signed.
    140      * @param signingKey the private key for signing.
    141      * @param signingEngine the signature signing engine.
    142      *
    143      * @throws    IOException if an error occurs during serialization
    144      * @throws    InvalidKeyException if the key is invalid.
    145      * @throws    SignatureException if signing fails.
    146      */
    147     public SignedObject(Serializable object, PrivateKey signingKey,
    148                         Signature signingEngine)
    149         throws IOException, InvalidKeyException, SignatureException {
    150             // creating a stream pipe-line, from a to b
    151             ByteArrayOutputStream b = new ByteArrayOutputStream();
    152             ObjectOutput a = new ObjectOutputStream(b);
    153
    154             // write and flush the object content to byte array
    155             a.writeObject(object);
    156             a.flush();
    157             a.close();
    158             this.content = b.toByteArray();
    159             b.close();
    160
    161             // now sign the encapsulated object
    162             this.sign(signingKey, signingEngine);
    163     }
    164
    165     /**
    166      * Retrieves the encapsulated object.
    167      * The encapsulated object is de-serialized before it is returned.
    168      *
    169      * @return the encapsulated object.
    170      *
    171      * @throws    IOException if an error occurs during de-serialization
    172      * @throws    ClassNotFoundException if an error occurs during
    173      * de-serialization
    174      */
    175     public Object getObject()
    176         throws IOException, ClassNotFoundException
    177     {
    178         // creating a stream pipe-line, from b to a
    179         ByteArrayInputStream b = new ByteArrayInputStream(this.content);
    180         ObjectInput a = new ObjectInputStream(b);
    181         Object obj = a.readObject();
    182         b.close();
    183         a.close();
    184         return obj;
    185     }
    186
    187     /**
    188      * Retrieves the signature on the signed object, in the form of a
    189      * byte array.
    190      *
    191      * @return the signature. Returns a new array each time this
    192      * method is called.
    193      */
    194     public byte[] getSignature() {
    195         return this.signature.clone();
    196     }
    197
    198     /**
    199      * Retrieves the name of the signature algorithm.
    200      *
    201      * @return the signature algorithm name.
    202      */
    203     public String getAlgorithm() {
    204         return this.thealgorithm;
    205     }
    206
    207     /**
    208      * Verifies that the signature in this SignedObject is the valid
    209      * signature for the object stored inside, with the given
    210      * verification key, using the designated verification engine.
    211      *
    212      * @param verificationKey the public key for verification.
    213      * @param verificationEngine the signature verification engine.
    214      *
    215      * @throws    SignatureException if signature verification failed (an
    216      *     exception prevented the signature verification engine from completing
    217      *     normally).
    218      * @throws    InvalidKeyException if the verification key is invalid.
    219      *
    220      * @return {@code true} if the signature
    221      * is valid, {@code false} otherwise
    222      */
    223     public boolean verify(PublicKey verificationKey,
    224                           Signature verificationEngine)
    225          throws InvalidKeyException, SignatureException {
    226              verificationEngine.initVerify(verificationKey);
    227              verificationEngine.update(this.content.clone());
    228              return verificationEngine.verify(this.signature.clone());
    229     }
    230
    231     /*
    232      * Signs the encapsulated object with the given signing key, using the
    233      * designated signature engine.
    234      *
    235      * @param signingKey the private key for signing.
    236      * @param signingEngine the signature signing engine.
    237      *
    238      * @throws    InvalidKeyException if the key is invalid.
    239      * @throws    SignatureException if signing fails.
    240      */
    241     private void sign(PrivateKey signingKey, Signature signingEngine)
    242         throws InvalidKeyException, SignatureException {
    243             // initialize the signing engine
    244             signingEngine.initSign(signingKey);
    245             signingEngine.update(this.content.clone());
    246             this.signature = signingEngine.sign().clone();
    247             this.thealgorithm = signingEngine.getAlgorithm();
    248     }
    249
    250     /**
    251      * readObject is called to restore the state of the SignedObject from
    252      * a stream.

    253      */
    254     @java.io.Serial
    255     private void readObject(java.io.ObjectInputStream s)
    256         throws java.io.IOException, ClassNotFoundException {
    257             java.io.ObjectInputStream.GetField fields = s.readFields();
    258             content = ((byte[])fields.get("content", null)).clone();
    259             signature = ((byte[])fields.get("signature", null)).clone();
    260             thealgorithm = (String)fields.get("thealgorithm", null);
    261     }
    262 }
    --- EOF ---