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 <drepper@redhat.com> 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 <ch@lathspell.de> 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}