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 * Conversion to Kotlin and from there to Java in 2012 by Christian Hammers <ch@lathspell.de> 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}