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