Coverage Summary for Class: Digest (org.ethereum.crypto.cryptohash)
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 <thomas.pornin@cryptolog.com>
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 }