Source code
Description: source: package: org.apache.commons.codec.digest, class: Sha2Crypt

    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      https://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.codec.digest;
    018
    019import java.nio.charset.StandardCharsets;
    020import java.security.MessageDigest;
    021import java.security.NoSuchAlgorithmException;
    022import java.security.SecureRandom;
    023import java.util.Arrays;
    024import java.util.Random;
    025import java.util.regex.Matcher;
    026import java.util.regex.Pattern;
    027
    028/**
    029 * SHA2-based Unix crypt implementation.
    030 * <p>
    031 * Based on the C implementation released into the Public Domain by Ulrich Drepper &lt;drepper@redhat.com&gt;
    032 * http://www.akkadia.org/drepper/SHA-crypt.txt
    033 * </p>
    034 * <p>
    035 * Conversion to Kotlin and from there to Java in 2012 by Christian Hammers &lt;ch@lathspell.de&gt; and likewise put
    036 * into the Public Domain.
    037 * </p>
    038 * <p>
    039 * This class is immutable and thread-safe.
    040 * </p>
    041 *
    042 * @since 1.7
    043 */
    044public class Sha2Crypt {
    045
    046    /** Default number of rounds if not explicitly specified. */
    047    private static final int ROUNDS_DEFAULT = 5000;
    048
    049    /** Maximum number of rounds. */
    050    private static final int ROUNDS_MAX = 999_999_999;
    051
    052    /** Minimum number of rounds. */
    053    private static final int ROUNDS_MIN = 1000;
    054
    055    /** Prefix for optional rounds specification. */
    056    private static final String ROUNDS_PREFIX = "rounds=";
    057
    058    /** The number of bytes the final hash value will have (SHA-256 variant). */
    059    private static final int SHA256_BLOCKSIZE = 32;
    060
    061    /** The prefixes that can be used to identify this crypt() variant (SHA-256). */
    062    static final String SHA256_PREFIX = "$5$";
    063
    064    /** The number of bytes the final hash value will have (SHA-512 variant). */
    065    private static final int SHA512_BLOCKSIZE = 64;
    066
    067    /** The prefixes that can be used to identify this crypt() variant (SHA-512). */
    068    static final String SHA512_PREFIX = "$6$";
    069
    070    /** The pattern to match valid salt values. */
    071    private static final Pattern SALT_PATTERN = Pattern
    072            .compile("^\\$([56])\\$(rounds=(\\d+)\\$)?([\\.\\/a-zA-Z0-9]{1,16}).*");
    073
    074    /**
    075     * Generates a libc crypt() compatible "$5$" hash value with random salt.
    076     *
    077     * <p>
    078     * See {@link Crypt#crypt(String, String)} for details.
    079     * </p>
    080     * <p>
    081     * A salt is generated for you using {@link SecureRandom}.
    082     * </p>
    083     *
    084     * @param keyBytes Plaintext to hash. Each array element is set to {@code 0} before returning.
    085     * @return The Complete hash value.
    086     * @throws IllegalArgumentException Thrown if a {@link NoSuchAlgorithmException} is caught.
    087     */
    088    public static String sha256Crypt(final byte[] keyBytes) {
    089        return sha256Crypt(keyBytes, null);
    090    }
    091
    092    /**
    093     * Generates a libc6 crypt() compatible "$5$" hash value.
    094     * <p>
    095     * See {@link Crypt#crypt(String, String)} for details.
    096     * </p>
    097     *
    098     * @param keyBytes Plaintext to hash. Each array element is set to {@code 0} before returning.
    099     * @param salt     real salt value without prefix or "rounds=". The salt may be null, in which case a salt is generated for you using {@link SecureRandom}.
    100     *                 If one does not want to use {@link SecureRandom}, you can pass your own {@link Random} in {@link #sha256Crypt(byte[], String, Random)}.
    101     * @return The Complete hash value including salt.
    102     * @throws IllegalArgumentException Thrown if the salt does not match the allowed pattern.
    103     * @throws IllegalArgumentException Thrown if a {@link NoSuchAlgorithmException} is caught.
    104     */
    105    public static String sha256Crypt(final byte[] keyBytes, String salt) {
    106        if (salt == null) {
    107            salt = SHA256_PREFIX + B64.getRandomSalt(8);
    108        }
    109        return sha2Crypt(keyBytes, salt, SHA256_PREFIX, SHA256_BLOCKSIZE, MessageDigestAlgorithms.SHA_256);
    110    }
    111
    112    /**
    113     * Generates a libc6 crypt() compatible "$5$" hash value.
    114     * <p>
    115     * See {@link Crypt#crypt(String, String)} for details.
    116     * </p>
    117     *
    118     * @param keyBytes plaintext to hash. Each array element is set to {@code 0} before returning.
    119     * @param salt     real salt value without prefix or "rounds=".
    120     * @param random   The instance of {@link Random} to use for generating the salt. Consider using {@link SecureRandom} for more secure salts.
    121     * @return The Complete hash value including salt.
    122     * @throws IllegalArgumentException Thrown if the salt does not match the allowed pattern.
    123     * @throws IllegalArgumentException Thrown if a {@link NoSuchAlgorithmException} is caught.
    124     * @since 1.12
    125     */
    126    public static String sha256Crypt(final byte[] keyBytes, String salt, final Random random) {
    127        if (salt == null) {
    128            salt = SHA256_PREFIX + B64.getRandomSalt(8, random);
    129        }
    130        return sha2Crypt(keyBytes, salt, SHA256_PREFIX, SHA256_BLOCKSIZE, MessageDigestAlgorithms.SHA_256);
    131    }
    132
    133    /**
    134     * Generates a libc6 crypt() compatible "$5$" or "$6$" SHA2 based hash value.
    135     * <p>
    136     * This is a nearly line by line conversion of the original C function. The numbered comments are from the algorithm description, the short C-style ones
    137     * from the original C code and the ones with "Remark" from me.
    138     * </p>
    139     * <p>
    140     * See {@link Crypt#crypt(String, String)} for details.
    141     * </p>
    142     *
    143     * @param keyBytes   plaintext to hash. Each array element is set to {@code 0} before returning.
    144     * @param salt       real salt value without prefix or {@code "rounds="}; may not be null.
    145     * @param saltPrefix either {@code $5$} or {@code $6$}.
    146     * @param blocksize  A value that differs between {@code $5$}  and {@code $6$}.
    147     * @param algorithm  {@link MessageDigest} algorithm identifier string.
    148     * @return The Complete hash value including prefix and salt.
    149     * @throws IllegalArgumentException Thrown if the given salt is {@code null} or does not match the allowed pattern.
    150     * @throws IllegalArgumentException Thrown if a {@link NoSuchAlgorithmException} is caught.
    151     * @see MessageDigestAlgorithms
    152     */
    153    private static String sha2Crypt(final byte[] keyBytes, final String salt, final String saltPrefix,
    154            final int blocksize, final String algorithm) {
    155
    156        final int keyLen = keyBytes.length;
    157
    158        // Extracts effective salt and the number of rounds from the given salt.
    159        int rounds = ROUNDS_DEFAULT;
    160        boolean roundsCustom = false;
    161        if (salt == null) {
    162            throw new IllegalArgumentException("Salt must not be null");
    163        }
    164
    165        final Matcher m = SALT_PATTERN.matcher(salt);
    166        if (!m.find()) {
    167            throw new IllegalArgumentException("Invalid salt value: " + salt);
    168        }
    169        if (m.group(3) != null) {
    170            rounds = Integer.parseInt(m.group(3));
    171            rounds = Math.max(ROUNDS_MIN, Math.min(ROUNDS_MAX, rounds));
    172            roundsCustom = true;
    173        }
    174        final String saltString = m.group(4);
    175        final byte[] saltBytes = saltString.getBytes(StandardCharsets.UTF_8);
    176        final int saltLen = saltBytes.length;
    177
    178        // 1. start digest A
    179        // Prepare for the real work.
    180        MessageDigest messageDigest = DigestUtils.getDigest(algorithm);
    181
    182        // 2. the password string is added to digest A
    183        /*
    184         * Add the key string.
    185         */
    186        messageDigest.update(keyBytes);
    187
    188        // 3. the salt string is added to digest A. This is just the salt string
    189        // itself without the enclosing '$', without the magic salt_prefix $5$ and
    190        // $6$ respectively and without the rounds=<N> specification.
    191        //
    192        // NB: the MD5 algorithm did add the $1$ salt_prefix. This is not deemed
    193        // necessary since it is a constant string and does not add security
    194        // and /possibly/ allows a plain text attack. Since the rounds=<N>
    195        // specification should never be added this would also create an
    196        // inconsistency.
    197        /*
    198         * The last part is the salt string. This must be at most 16 characters and it ends at the first `$' character
    199         * (for compatibility with existing implementations).
    200         */
    201        messageDigest.update(saltBytes);
    202
    203        // 4. start digest B
    204        /*
    205         * Compute alternate sha512 sum with input KEY, SALT, and KEY. The final result will be added to the first
    206         * context.
    207         */
    208        MessageDigest altMessageDigestMd5 = DigestUtils.getDigest(algorithm);
    209
    210        // 5. add the password to digest B
    211        /*
    212         * Add key.
    213         */
    214        altMessageDigestMd5.update(keyBytes);
    215
    216        // 6. add the salt string to digest B
    217        /*
    218         * Add salt.
    219         */
    220        altMessageDigestMd5.update(saltBytes);
    221
    222        // 7. add the password again to digest B
    223        /*
    224         * Add key again.
    225         */
    226        altMessageDigestMd5.update(keyBytes);
    227
    228        // 8. finish digest B
    229        /*
    230         * Now get result of this (32 bytes) and add it to the other context.
    231         */
    232        byte[] altResult = altMessageDigestMd5.digest();
    233
    234        // 9. For each block of 32 or 64 bytes in the password string (excluding
    235        // the terminating NUL in the C representation), add digest B to digest A
    236        /*
    237         * Add for any character in the key one byte of the alternate sum.
    238         */
    239        /*
    240         * (Remark: the C code comment seems wrong for key length > 32!)
    241         */
    242        int cnt = keyBytes.length;
    243        while (cnt > blocksize) {
    244            messageDigest.update(altResult, 0, blocksize);
    245            cnt -= blocksize;
    246        }
    247
    248        // 10. For the remaining N bytes of the password string add the first
    249        // N bytes of digest B to digest A
    250        messageDigest.update(altResult, 0, cnt);
    251
    252        // 11. For each bit of the binary representation of the length of the
    253        // password string up to and including the highest 1-digit, starting
    254        // from to the lowest bit position (numeric value 1):
    255        //
    256        // a) for a 1-digit add digest B to digest A
    257        //
    258        // b) for a 0-digit add the password string
    259        //
    260        // NB: this step differs significantly from the MD5 algorithm. It
    261        // adds more randomness.
    262        /*
    263         * Take the binary representation of the length of the key and for every 1 add the alternate sum, for every 0
    264         * the key.
    265         */
    266        cnt = keyBytes.length;
    267        while (cnt > 0) {
    268            if ((cnt & 1) != 0) {
    269                messageDigest.update(altResult, 0, blocksize);
    270            } else {
    271                messageDigest.update(keyBytes);
    272            }
    273            cnt >>= 1;
    274        }
    275
    276        // 12. finish digest A
    277        /*
    278         * Create intermediate result.
    279         */
    280        altResult = messageDigest.digest();
    281
    282        // 13. start digest DP
    283        /*
    284         * Start computation of P byte sequence.
    285         */
    286        altMessageDigestMd5 = DigestUtils.getDigest(algorithm);
    287
    288        // 14. for every byte in the password (excluding the terminating NUL byte
    289        // in the C representation of the string)
    290        //
    291        // add the password to digest DP
    292        /*
    293         * For every character in the password add the entire password.
    294         */
    295        for (int i = 1; i <= keyLen; i++) {
    296            altMessageDigestMd5.update(keyBytes);
    297        }
    298
    299        // 15. finish digest DP
    300        /*
    301         * Finish the digest.
    302         */
    303        byte[] tempResult = altMessageDigestMd5.digest();
    304
    305        // 16. produce byte sequence P of the same length as the password where
    306        //
    307        // a) for each block of 32 or 64 bytes of length of the password string
    308        // the entire digest DP is used
    309        //
    310        // b) for the remaining N (up to 31 or 63) bytes use the first N
    311        // bytes of digest DP
    312        /*
    313         * Create byte sequence P.
    314         */
    315        final byte[] bytes = new byte[keyLen];
    316        int cp = 0;
    317        while (cp < keyLen - blocksize) {
    318            System.arraycopy(tempResult, 0, bytes, cp, blocksize);
    319            cp += blocksize;
    320        }
    321        System.arraycopy(tempResult, 0, bytes, cp, keyLen - cp);
    322
    323        // 17. start digest DS
    324        /*
    325         * Start computation of S byte sequence.
    326         */
    327        altMessageDigestMd5 = DigestUtils.getDigest(algorithm);
    328
    329        // 18. repeat the following 16+A[0] times, where A[0] represents the first
    330        // byte in digest A interpreted as an 8-bit unsigned value
    331        //
    332        // add the salt to digest DS
    333        /*
    334         * For every character in the password add the entire password.
    335         */
    336        for (int i = 1; i <= 16 + (altResult[0] & 0xff); i++) {
    337            altMessageDigestMd5.update(saltBytes);
    338        }
    339
    340        // 19. finish digest DS
    341        /*
    342         * Finish the digest.
    343         */
    344        tempResult = altMessageDigestMd5.digest();
    345
    346        // 20. produce byte sequence S of the same length as the salt string where
    347        //
    348        // a) for each block of 32 or 64 bytes of length of the salt string
    349        // the entire digest DS is used
    350        //
    351        // b) for the remaining N (up to 31 or 63) bytes use the first N
    352        // bytes of digest DS
    353        /*
    354         * Create byte sequence S.
    355         */
    356        // Remark: The salt is limited to 16 chars, how does this make sense?
    357        final byte[] sBytes = new byte[saltLen];
    358        cp = 0;
    359        while (cp < saltLen - blocksize) {
    360            System.arraycopy(tempResult, 0, sBytes, cp, blocksize);
    361            cp += blocksize;
    362        }
    363        System.arraycopy(tempResult, 0, sBytes, cp, saltLen - cp);
    364
    365        // 21. repeat a loop according to the number specified in the rounds=<N>
    366        // specification in the salt (or the default value if none is
    367        // present). Each round is numbered, starting with 0 and up to N-1.
    368        //
    369        // The loop uses a digest as input. In the first round it is the
    370        // digest produced in step 12. In the latter steps it is the digest
    371        // produced in step 21.h. The following text uses the notation
    372        // "digest A/C" to describe this behavior.
    373        /*
    374         * Repeatedly run the collected hash value through sha512 to burn CPU cycles.
    375         */
    376        for (int i = 0; i <= rounds - 1; i++) {
    377            // a) start digest C
    378            /*
    379             * New context.
    380             */
    381            messageDigest = DigestUtils.getDigest(algorithm);
    382
    383            // b) for odd round numbers add the byte sequence P to digest C
    384            // c) for even round numbers add digest A/C
    385            /*
    386             * Add key or last result.
    387             */
    388            if ((i & 1) != 0) {
    389                messageDigest.update(bytes, 0, keyLen);
    390            } else {
    391                messageDigest.update(altResult, 0, blocksize);
    392            }
    393
    394            // d) for all round numbers not divisible by 3 add the byte sequence S
    395            /*
    396             * Add salt for numbers not divisible by 3.
    397             */
    398            if (i % 3 != 0) {
    399                messageDigest.update(sBytes, 0, saltLen);
    400            }
    401
    402            // e) for all round numbers not divisible by 7 add the byte sequence P
    403            /*
    404             * Add key for numbers not divisible by 7.
    405             */
    406            if (i % 7 != 0) {
    407                messageDigest.update(bytes, 0, keyLen);
    408            }
    409
    410            // f) for odd round numbers add digest A/C
    411            // g) for even round numbers add the byte sequence P
    412            /*
    413             * Add key or last result.
    414             */
    415            if ((i & 1) != 0) {
    416                messageDigest.update(altResult, 0, blocksize);
    417            } else {
    418                messageDigest.update(bytes, 0, keyLen);
    419            }
    420
    421            // h) finish digest C.
    422            /*
    423             * Create intermediate result.
    424             */
    425            altResult = messageDigest.digest();
    426        }
    427
    428        // 22. Produce the output string. This is an ASCII string of the maximum
    429        // size specified above, consisting of multiple pieces:
    430        //
    431        // a) the salt salt_prefix, $5$ or $6$ respectively
    432        //
    433        // b) the rounds=<N> specification, if one was present in the input
    434        // salt string. A trailing '$' is added in this case to separate
    435        // the rounds specification from the following text.
    436        //
    437        // c) the salt string truncated to 16 characters
    438        //
    439        // d) a '$' character
    440        /*
    441         * Now we can construct the result string. It consists of three parts.
    442         */
    443        final StringBuilder buffer = new StringBuilder(saltPrefix);
    444        if (roundsCustom) {
    445            buffer.append(ROUNDS_PREFIX);
    446            buffer.append(rounds);
    447            buffer.append("$");
    448        }
    449        buffer.append(saltString);
    450        buffer.append("$");
    451
    452        // e) the base-64 encoded final C digest. The encoding used is as
    453        // follows:
    454        // [...]
    455        //
    456        // Each group of three bytes from the digest produces four
    457        // characters as output:
    458        //
    459        // 1. character: the six low bits of the first byte
    460        // 2. character: the two high bits of the first byte and the
    461        // four low bytes from the second byte
    462        // 3. character: the four high bytes from the second byte and
    463        // the two low bits from the third byte
    464        // 4. character: the six high bits from the third byte
    465        //
    466        // The groups of three bytes are as follows (in this sequence).
    467        // These are the indices into the byte array containing the
    468        // digest, starting with index 0. For the last group there are
    469        // not enough bytes left in the digest and the value zero is used
    470        // in its place. This group also produces only three or two
    471        // characters as output for SHA-512 and SHA-512 respectively.
    472
    473        // This was just a safeguard in the C implementation:
    474        // int buflen = salt_prefix.length() - 1 + ROUNDS_PREFIX.length() + 9 + 1 + salt_string.length() + 1 + 86 + 1;
    475
    476        if (blocksize == 32) {
    477            B64.b64from24bit(altResult[0], altResult[10], altResult[20], 4, buffer);
    478            B64.b64from24bit(altResult[21], altResult[1], altResult[11], 4, buffer);
    479            B64.b64from24bit(altResult[12], altResult[22], altResult[2], 4, buffer);
    480            B64.b64from24bit(altResult[3], altResult[13], altResult[23], 4, buffer);
    481            B64.b64from24bit(altResult[24], altResult[4], altResult[14], 4, buffer);
    482            B64.b64from24bit(altResult[15], altResult[25], altResult[5], 4, buffer);
    483            B64.b64from24bit(altResult[6], altResult[16], altResult[26], 4, buffer);
    484            B64.b64from24bit(altResult[27], altResult[7], altResult[17], 4, buffer);
    485            B64.b64from24bit(altResult[18], altResult[28], altResult[8], 4, buffer);
    486            B64.b64from24bit(altResult[9], altResult[19], altResult[29], 4, buffer);
    487            B64.b64from24bit((byte) 0, altResult[31], altResult[30], 3, buffer);
    488        } else {
    489            B64.b64from24bit(altResult[0], altResult[21], altResult[42], 4, buffer);
    490            B64.b64from24bit(altResult[22], altResult[43], altResult[1], 4, buffer);
    491            B64.b64from24bit(altResult[44], altResult[2], altResult[23], 4, buffer);
    492            B64.b64from24bit(altResult[3], altResult[24], altResult[45], 4, buffer);
    493            B64.b64from24bit(altResult[25], altResult[46], altResult[4], 4, buffer);
    494            B64.b64from24bit(altResult[47], altResult[5], altResult[26], 4, buffer);
    495            B64.b64from24bit(altResult[6], altResult[27], altResult[48], 4, buffer);
    496            B64.b64from24bit(altResult[28], altResult[49], altResult[7], 4, buffer);
    497            B64.b64from24bit(altResult[50], altResult[8], altResult[29], 4, buffer);
    498            B64.b64from24bit(altResult[9], altResult[30], altResult[51], 4, buffer);
    499            B64.b64from24bit(altResult[31], altResult[52], altResult[10], 4, buffer);
    500            B64.b64from24bit(altResult[53], altResult[11], altResult[32], 4, buffer);
    501            B64.b64from24bit(altResult[12], altResult[33], altResult[54], 4, buffer);
    502            B64.b64from24bit(altResult[34], altResult[55], altResult[13], 4, buffer);
    503            B64.b64from24bit(altResult[56], altResult[14], altResult[35], 4, buffer);
    504            B64.b64from24bit(altResult[15], altResult[36], altResult[57], 4, buffer);
    505            B64.b64from24bit(altResult[37], altResult[58], altResult[16], 4, buffer);
    506            B64.b64from24bit(altResult[59], altResult[17], altResult[38], 4, buffer);
    507            B64.b64from24bit(altResult[18], altResult[39], altResult[60], 4, buffer);
    508            B64.b64from24bit(altResult[40], altResult[61], altResult[19], 4, buffer);
    509            B64.b64from24bit(altResult[62], altResult[20], altResult[41], 4, buffer);
    510            B64.b64from24bit((byte) 0, (byte) 0, altResult[63], 2, buffer);
    511        }
    512
    513        /*
    514         * Clear the buffer for the intermediate result so that people attaching to processes or reading core dumps
    515         * cannot get any information.
    516         */
    517        // Is there a better way to do this with the JVM?
    518        Arrays.fill(tempResult, (byte) 0);
    519        Arrays.fill(bytes, (byte) 0);
    520        Arrays.fill(sBytes, (byte) 0);
    521        messageDigest.reset();
    522        altMessageDigestMd5.reset();
    523        Arrays.fill(keyBytes, (byte) 0);
    524        Arrays.fill(saltBytes, (byte) 0);
    525
    526        return buffer.toString();
    527    }
    528
    529    /**
    530     * Generates a libc crypt() compatible "$6$" hash value with random salt.
    531     *
    532     * <p>
    533     * See {@link Crypt#crypt(String, String)} for details.
    534     * </p>
    535     * <p>
    536     * A salt is generated for you using {@link SecureRandom}.
    537     * </p>
    538     *
    539     * @param keyBytes Plaintext to hash. Each array element is set to {@code 0} before returning.
    540     * @return Complete hash value.
    541     * @throws IllegalArgumentException Thrown if a {@link NoSuchAlgorithmException} is caught.
    542     */
    543    public static String sha512Crypt(final byte[] keyBytes) {
    544        return sha512Crypt(keyBytes, null);
    545    }
    546
    547    /**
    548     * Generates a libc6 crypt() compatible "$6$" hash value.
    549     *
    550     * <p>
    551     * See {@link Crypt#crypt(String, String)} for details.
    552     * </p>
    553     *
    554     * @param keyBytes Plaintext to hash. Each array element is set to {@code 0} before returning.
    555     * @param salt     Real salt value without prefix or "rounds=". The salt may be null, in which case a salt is generated for you using {@link SecureRandom};
    556     *                 if you want to use a {@link Random} object other than {@link SecureRandom} then we suggest you provide it using
    557     *                 {@link #sha512Crypt(byte[], String, Random)}.
    558     * @return Complete hash value including salt.
    559     * @throws IllegalArgumentException Thrown if the salt does not match the allowed pattern.
    560     * @throws IllegalArgumentException Thrown if a {@link NoSuchAlgorithmException} is caught.
    561     */
    562    public static String sha512Crypt(final byte[] keyBytes, String salt) {
    563        if (salt == null) {
    564            salt = SHA512_PREFIX + B64.getRandomSalt(8);
    565        }
    566        return sha2Crypt(keyBytes, salt, SHA512_PREFIX, SHA512_BLOCKSIZE, MessageDigestAlgorithms.SHA_512);
    567    }
    568
    569    /**
    570     * Generates a libc6 crypt() compatible "$6$" hash value.
    571     *
    572     * <p>
    573     * See {@link Crypt#crypt(String, String)} for details.
    574     * </p>
    575     *
    576     * @param keyBytes Plaintext to hash. Each array element is set to {@code 0} before returning.
    577     * @param salt     Real salt value without prefix or "rounds=". The salt may be null, in which case a salt is generated for you using {@link SecureRandom}.
    578     * @param random   The instance of {@link Random} to use for generating the salt. Consider using {@link SecureRandom} for more secure salts.
    579     * @return Complete hash value including salt.
    580     * @throws IllegalArgumentException if the salt does not match the allowed pattern.
    581     * @throws IllegalArgumentException Thrown if a {@link NoSuchAlgorithmException} is caught.
    582     * @since 1.12
    583     */
    584    public static String sha512Crypt(final byte[] keyBytes, String salt, final Random random) {
    585        if (salt == null) {
    586            salt = SHA512_PREFIX + B64.getRandomSalt(8, random);
    587        }
    588        return sha2Crypt(keyBytes, salt, SHA512_PREFIX, SHA512_BLOCKSIZE, MessageDigestAlgorithms.SHA_512);
    589    }
    590
    591    /**
    592     * Consider private.
    593     *
    594     * @deprecated Will be private in the next major version.
    595     */
    596    @Deprecated
    597    public Sha2Crypt() {
    598        // empty
    599    }
    600}