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 }