Home | History | Annotate | Download | only in security 
      1 /*
      2  *  Licensed to the Apache Software Foundation (ASF) under one or more
      3  *  contributor license agreements.  See the NOTICE file distributed with
      4  *  this work for additional information regarding copyright ownership.
      5  *  The ASF licenses this file to You under the Apache License, Version 2.0
      6  *  (the "License"); you may not use this file except in compliance with
      7  *  the License.  You may obtain a copy of the License at
      8  *
      9  *     http://www.apache.org/licenses/LICENSE-2.0
     10  *
     11  *  Unless required by applicable law or agreed to in writing, software
     12  *  distributed under the License is distributed on an "AS IS" BASIS,
     13  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     14  *  See the License for the specific language governing permissions and
     15  *  limitations under the License.
     16  */
     17 
     18 package java.security;
     19 
     20 import java.io.FilterInputStream;
     21 import java.io.IOException;
     22 import java.io.InputStream;
     23 
     24 /**
     25  * {@code DigestInputStream} is a {@code FilterInputStream} which maintains an
     26  * associated message digest.
     27  */
     28 public class DigestInputStream extends FilterInputStream {
     29 
     30     /**
     31      * The message digest for this stream.
     32      */
     33     protected MessageDigest digest;
     34 
     35     // Indicates whether digest functionality is on or off
     36     private boolean isOn = true;
     37 
     38     /**
     39      * Constructs a new instance of this {@code DigestInputStream}, using the
     40      * given {@code stream} and the {@code digest}.
     41      *
     42      * <p><strong>Warning:</strong> passing a null source creates an invalid
     43      * {@code DigestInputStream}. All operations on such a stream will fail.
     44      *
     45      * @param stream
     46      *            the input stream.
     47      * @param digest
     48      *            the message digest.
     49      */
     50     public DigestInputStream(InputStream stream, MessageDigest digest) {
     51         super(stream);
     52         this.digest = digest;
     53     }
     54 
     55     /**
     56      * Returns the message digest for this stream.
     57      *
     58      * @return the message digest for this stream.
     59      */
     60     public MessageDigest getMessageDigest() {
     61         return digest;
     62     }
     63 
     64     /**
     65      * Sets the message digest which this stream will use.
     66      *
     67      * @param digest
     68      *            the message digest which this stream will use.
     69      */
     70     public void setMessageDigest(MessageDigest digest) {
     71         this.digest = digest;
     72     }
     73 
     74     /**
     75      * Reads the next byte and returns it as an {@code int}. Updates the digest
     76      * for the byte if this function is {@link #on(boolean)}.
     77      * <p>
     78      * This operation is blocking.
     79      *
     80      * @return the byte which was read or -1 at end of stream.
     81      * @throws IOException
     82      *             if reading the source stream causes an {@code IOException}.
     83      */
     84     @Override
     85     public int read() throws IOException {
     86         // read the next byte
     87         int byteRead = in.read();
     88         // update digest only if
     89         // - digest functionality is on
     90         // - eos has not been reached
     91         if (isOn && (byteRead != -1)) {
     92             digest.update((byte)byteRead);
     93         }
     94         // return byte read
     95         return byteRead;
     96     }
     97 
     98     /**
     99      * Reads up to {@code byteCount} bytes into {@code buffer}, starting at
    100      * {@code byteOffset}. Updates the digest if this function is
    101      * {@link #on(boolean)}.
    102      *
    103      * <p>This operation is blocking.
    104      *
    105      * <p>Returns the number of bytes actually read or -1 if the end of the
    106      * filtered stream has been reached while reading.
    107      *
    108      * @throws IOException
    109      *             if reading the source stream causes an {@code IOException}
    110      */
    111     @Override
    112     public int read(byte[] buffer, int byteOffset, int byteCount) throws IOException {
    113         int bytesRead = in.read(buffer, byteOffset, byteCount);
    114         // update digest only if
    115         // - digest functionality is on
    116         // - eos has not been reached
    117         if (isOn && (bytesRead != -1)) {
    118             digest.update(buffer, byteOffset, bytesRead);
    119         }
    120         // return number of bytes read
    121         return bytesRead;
    122     }
    123 
    124     /**
    125      * Enables or disables the digest function (default is on).
    126      *
    127      * @param on
    128      *            {@code true} if the digest should be computed, {@code false}
    129      *            otherwise.
    130      * @see MessageDigest
    131      */
    132     public void on(boolean on) {
    133         isOn = on;
    134     }
    135 
    136     /**
    137      * Returns a string containing a concise, human-readable description of this
    138      * {@code DigestInputStream} including the digest.
    139      *
    140      * @return a printable representation for this {@code DigestInputStream}.
    141      */
    142     @Override
    143     public String toString() {
    144         return super.toString() + ", " + digest.toString() +
    145             (isOn ? ", is on" : ", is off");
    146     }
    147 }
    148