Package: Pbkdf2PasswordHash

Pbkdf2PasswordHash

Coverage

1: /*
2: * Copyright (c) 2015, 2020 Oracle and/or its affiliates. All rights reserved.
3: *
4: * This program and the accompanying materials are made available under the
5: * terms of the Eclipse Public License v. 2.0, which is available at
6: * http://www.eclipse.org/legal/epl-2.0.
7: *
8: * This Source Code may also be made available under the following Secondary
9: * Licenses when the conditions for such availability set forth in the
10: * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
11: * version 2 with the GNU Classpath Exception, which is available at
12: * https://www.gnu.org/software/classpath/license.html.
13: *
14: * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
15: */
16:
17: package jakarta.security.enterprise.identitystore;
18:
19: /**
20: * This interface represents the built-in {@code Pbkdf2PasswordHash} implementation.
21: * <p>
22: * To use {@code Pbkdf2PasswordHash} with the built-in Database {@link IdentityStore},
23: * configure this interface type as the {@code hashAlgorithm} value
24: * on the {@link DatabaseIdentityStoreDefinition} annotation.
25: * <p>
26: * To configure parameters for {@code Pbkdf2PasswordHash}, specify them as the
27: * {@code hashAlgorithmParameters} value on the {@link DatabaseIdentityStoreDefinition} annotation.
28: * <p>
29: * The built-in implementation must support the following configurable parameters:
30: * <blockquote><pre>
31: Pbkdf2PasswordHash.Algorithm // default "PBKDF2WithHmacSHA256"
32: Pbkdf2PasswordHash.Iterations // default 2048, minimum 1024
33: Pbkdf2PasswordHash.SaltSizeBytes // default 32, minimum 16
34: Pbkdf2PasswordHash.KeySizeBytes // default 32, minimum 16
35: * </pre></blockquote>
36: * <p>
37: * And the following PBKDF2 algorithms:
38: * <blockquote><pre>
39: PBKDF2WithHmacSHA224
40: PBKDF2WithHmacSHA256
41: PBKDF2WithHmacSHA384
42: PBKDF2WithHmacSHA512
43: * </pre></blockquote>
44: * Algorithm names are the string literal names documented for the corresponding algorithms by the
45: * <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html" target="_top">
46: Java Cryptography Architecture Standard Algorithm Name Documentation</a>.
47: * <p>
48: * The encoded format produced by {@link #generate(char[])}, and consumed by {@link #verify(char[], String)},
49: * is as follows:
50: * <blockquote><pre>
51: {@code <algorithm>:<iterations>:<base64(salt)>:<base64(hash)>}
52: * </pre></blockquote>
53: * Where:
54: * <ul>
55: * <li><i>algorithm</i> -- the algorithm used to generate the hash
56: * <li><i>iterations</i> -- the number of iterations used to generate the hash
57: * <li><i>base64(salt)</i> -- the salt used to generate the hash, base64-encoded
58: * <li><i>base64(hash)</i> -- the hash value, base64-encoded
59: * </ul>
60: * <p>
61: * Because the algorithm and the parameters used to generate the hash are stored with the hash,
62: * the built-in {@code Pbkdf2PasswordHash} implementation can verify hashes generated using algorithm
63: * and parameter values that differ from the currently configured values. This means the configuration
64: * parameters can be changed without impacting the ability to verify existing password hashes.
65: * <p>
66: * (Password hashes generated using algorithms/parameters outside the range supported by
67: * {@code Pbkdf2PasswordHash} cannot be verified.)
68: *
69: * @see DatabaseIdentityStoreDefinition#hashAlgorithm()
70: * @see DatabaseIdentityStoreDefinition#hashAlgorithmParameters()
71: */
72: public interface Pbkdf2PasswordHash extends PasswordHash {
73:
74: }