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