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
20 package org.apache.shiro.crypto.hash;
21
22 import java.util.Random;
23 import java.util.Set;
24
25 /**
26 * Service Provider Interface for password hashing algorithms.
27 *
28 * <p>Apache Shiro will load algorithm implementations based on the method {@link #getImplementedAlgorithms()}.
29 * Loaded providers are expected to return a suitable hash implementation.</p>
30 *
31 * <p>Modern kdf-based hash implementations can extend the {@link AbstractCryptHash} class.</p>
32 *
33 * @since 2.0
34 */
35 public interface HashSpi {
36
37 /**
38 * A list of algorithms recognized by this implementation.
39 *
40 * <p>Example values are {@code argon2id} and {@code argon2i} for the Argon2 service provider and
41 * {@code 2y} and {@code 2a} for the BCrypt service provider.</p>
42 *
43 * @return a set of recognized algorithms.
44 */
45 Set<String> getImplementedAlgorithms();
46
47 /**
48 * Creates a Hash instance from the given format string recognized by this provider.
49 *
50 * <p>There is no global format which this provider must accept. Each provider can define their own
51 * format, but they are usually based on the {@code crypt(3)} formats used in {@code /etc/shadow} files.</p>
52 *
53 * <p>Implementations should overwrite this javadoc to add examples of the accepted formats.</p>
54 *
55 * @param format the format string to be parsed by this implementation.
56 * @return a class extending Hash.
57 */
58 Hash fromString(String format);
59
60 /**
61 * A factory class for the hash of the type {@code <T>}.
62 *
63 * <p>Implementations are highly encouraged to use the given random parameter as
64 * source of random bytes (e.g. for seeds).</p>
65 *
66 * @param random a source of {@link Random}, usually {@code SecureRandom}.
67 * @return a factory class for creating instances of {@code <T>}.
68 */
69 HashFactory newHashFactory(Random random);
70
71 interface HashFactory {
72
73 /**
74 * Generates a hash from the given hash request.
75 *
76 * <p>If the hash requests’ optional parameters are not set, the {@link HashFactory} implementation
77 * should use default parameters where applicable.</p>
78 * <p>If the hash requests’ salt is missing or empty, the implementation should create a salt
79 * with a default size.</p>
80 *
81 * @param hashRequest the request to build a Hash from.
82 * @return a generated Hash according to the specs.
83 * @throws IllegalArgumentException if any of the parameters is outside of valid boundaries (algorithm-specific)
84 * or if the given algorithm is not applicable for this {@link HashFactory}.
85 */
86 Hash generate(HashRequest hashRequest);
87 }
88 }