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}