1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.shiro.crypto.hash;
20
21 /**
22 * A {@code HashService} hashes input sources utilizing a particular hashing strategy.
23 * <p/>
24 * A {@code HashService} sits at a higher architectural level than Shiro's simple {@link Hash} classes: it allows
25 * for salting and iteration-related strategies to be configured and internalized in a
26 * single component that can be re-used in multiple places in the application.
27 * <p/>
28 * For example, for the most secure hashes, it is highly recommended to use a randomly generated salt, potentially
29 * paired with an configuration-specific private salt, in addition to using multiple hash iterations.
30 * <p/>
31 * While one can do this easily enough using Shiro's {@link Hash} implementations directly, this direct approach could
32 * quickly lead to copy-and-paste behavior. For example, consider this logic which might need to repeated in an
33 * application:
34 * <pre>
35 * int numHashIterations = ...
36 * ByteSource privateSalt = ...
37 * ByteSource randomSalt = {@link org.apache.shiro.crypto.RandomNumberGenerator randomNumberGenerator}.nextBytes();
38 * ByteSource combined = combine(privateSalt, randomSalt);
39 * Hash hash = Sha512Hash(source, combined, numHashIterations);
40 * save(hash);
41 * </pre>
42 * In this example, often only the input source will change during runtime, while the hashing strategy (how salts
43 * are generated or acquired, how many hash iterations will be performed, etc) usually remain consistent. A HashService
44 * internalizes this logic so the above becomes simply this:
45 * <pre>
46 * HashRequest request = new HashRequest.Builder().source(source).build();
47 * Hash result = hashService.hash(request);
48 * save(result);
49 * </pre>
50 *
51 * @since 1.2
52 */
53 public interface HashService {
54
55 /**
56 * Computes a hash based on the given request.
57 *
58 * <h3>Salt Notice</h3>
59 *
60 * If a salt accompanies the return value
61 * (i.e. <code>returnedHash.{@link org.apache.shiro.crypto.hash.Hash#getSalt() getSalt()} != null</code>), this
62 * same exact salt <b><em>MUST</em></b> be presented back to the {@code HashService} if hash
63 * comparison/verification will be performed at a later time (for example, for password hash or file checksum
64 * comparison).
65 * <p/>
66 * For additional security, the {@code HashService}'s internal implementation may use more complex salting
67 * strategies than what would be achieved by computing a {@code Hash} manually.
68 * <p/>
69 * In summary, if a {@link HashService} returns a salt in a returned Hash, it is expected that the same salt
70 * will be provided to the same {@code HashService} instance.
71 *
72 * @param request the request to process
73 * @return the hashed data
74 * @see Hash#getSalt()
75 */
76 Hash computeHash(HashRequest request);
77 }