Coverage Summary for Class: Digest (org.ethereum.crypto.cryptohash)

Class
Digest


1 /* 2  * This file is part of RskJ 3  * Copyright (C) 2017 RSK Labs Ltd. 4  * (derived from ethereumJ library, Copyright (c) 2016 <ether.camp>) 5  * 6  * This program is free software: you can redistribute it and/or modify 7  * it under the terms of the GNU Lesser General Public License as published by 8  * the Free Software Foundation, either version 3 of the License, or 9  * (at your option) any later version. 10  * 11  * This program is distributed in the hope that it will be useful, 12  * but WITHOUT ANY WARRANTY; without even the implied warranty of 13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14  * GNU Lesser General Public License for more details. 15  * 16  * You should have received a copy of the GNU Lesser General Public License 17  * along with this program. If not, see <http://www.gnu.org/licenses/>. 18  */ 19  20 // $Id: Digest.java 232 2010-06-17 14:19:24Z tp $ 21  22 package org.ethereum.crypto.cryptohash; 23  24 /** 25  * <p>This interface documents the API for a hash function. This 26  * interface somewhat mimics the standard {@code 27  * java.security.MessageDigest} class. We do not extend that class in 28  * order to provide compatibility with reduced Java implementations such 29  * as J2ME. Implementing a {@code java.security.Provider} compatible 30  * with Sun's JCA ought to be easy.</p> 31  * 32  * <p>A {@code Digest} object maintains a running state for a hash 33  * function computation. Data is inserted with {@code update()} calls; 34  * the result is obtained from a {@code digest()} method (where some 35  * final data can be inserted as well). When a digest output has been 36  * produced, the objet is automatically resetted, and can be used 37  * immediately for another digest operation. The state of a computation 38  * can be cloned with the {@link #copy} method; this can be used to get 39  * a partial hash result without interrupting the complete 40  * computation.</p> 41  * 42  * <p>{@code Digest} objects are stateful and hence not thread-safe; 43  * however, distinct {@code Digest} objects can be accessed concurrently 44  * without any problem.</p> 45  * 46  * <pre> 47  * ==========================(LICENSE BEGIN)============================ 48  * 49  * Copyright (c) 2007-2010 Projet RNRT SAPHIR 50  * 51  * Permission is hereby granted, free of charge, to any person obtaining 52  * a copy of this software and associated documentation files (the 53  * "Software"), to deal in the Software without restriction, including 54  * without limitation the rights to use, copy, modify, merge, publish, 55  * distribute, sublicense, and/or sell copies of the Software, and to 56  * permit persons to whom the Software is furnished to do so, subject to 57  * the following conditions: 58  * 59  * The above copyright notice and this permission notice shall be 60  * included in all copies or substantial portions of the Software. 61  * 62  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 63  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 64  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 65  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 66  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 67  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 68  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 69  * 70  * ===========================(LICENSE END)============================= 71  * </pre> 72  * 73  * @version $Revision: 232 $ 74  * @author Thomas Pornin &lt;thomas.pornin@cryptolog.com&gt; 75  */ 76  77 public interface Digest { 78  79  /** 80  * Insert one more input data byte. 81  * 82  * @param in the input byte 83  */ 84  public void update(byte in); 85  86  /** 87  * Insert some more bytes. 88  * 89  * @param inbuf the data bytes 90  */ 91  public void update(byte[] inbuf); 92  93  /** 94  * Insert some more bytes. 95  * 96  * @param inbuf the data buffer 97  * @param off the data offset in {@code inbuf} 98  * @param len the data length (in bytes) 99  */ 100  public void update(byte[] inbuf, int off, int len); 101  102  /** 103  * Finalize the current hash computation and return the hash value 104  * in a newly-allocated array. The object is resetted. 105  * 106  * @return the hash output 107  */ 108  public byte[] digest(); 109  110  /** 111  * Input some bytes, then finalize the current hash computation 112  * and return the hash value in a newly-allocated array. The object 113  * is resetted. 114  * 115  * @param inbuf the input data 116  * @return the hash output 117  */ 118  public byte[] digest(byte[] inbuf); 119  120  /** 121  * Finalize the current hash computation and store the hash value 122  * in the provided output buffer. The {@code len} parameter 123  * contains the maximum number of bytes that should be written; 124  * no more bytes than the natural hash function output length will 125  * be produced. If {@code len} is smaller than the natural 126  * hash output length, the hash output is truncated to its first 127  * {@code len} bytes. The object is resetted. 128  * 129  * @param outbuf the output buffer 130  * @param off the output offset within {@code outbuf} 131  * @param len the requested hash output length (in bytes) 132  * @return the number of bytes actually written in {@code outbuf} 133  */ 134  public int digest(byte[] outbuf, int off, int len); 135  136  /** 137  * Get the natural hash function output length (in bytes). 138  * 139  * @return the digest output length (in bytes) 140  */ 141  public int getDigestLength(); 142  143  /** 144  * Reset the object: this makes it suitable for a new hash 145  * computation. The current computation, if any, is discarded. 146  */ 147  public void reset(); 148  149  /** 150  * Clone the current state. The returned object evolves independantly 151  * of this object. 152  * 153  * @return the clone 154  */ 155  public Digest copy(); 156  157  /** 158  * <p>Return the "block length" for the hash function. This 159  * value is naturally defined for iterated hash functions 160  * (Merkle-Damgard). It is used in HMAC (that's what the 161  * <a href="http://tools.ietf.org/html/rfc2104">HMAC specification</a> 162  * names the "{@code B}" parameter).</p> 163  * 164  * <p>If the function is "block-less" then this function may 165  * return {@code -n} where {@code n} is an integer such that the 166  * block length for HMAC ("{@code B}") will be inferred from the 167  * key length, by selecting the smallest multiple of {@code n} 168  * which is no smaller than the key length. For instance, for 169  * the Fugue-xxx hash functions, this function returns -4: the 170  * virtual block length B is the HMAC key length, rounded up to 171  * the next multiple of 4.</p> 172  * 173  * @return the internal block length (in bytes), or {@code -n} 174  */ 175  public int getBlockLength(); 176  177  /** 178  * <p>Get the display name for this function (e.g. {@code "SHA-1"} 179  * for SHA-1).</p> 180  * 181  * @see Object 182  */ 183  public String toString(); 184 }