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.SecureRandom; 021import java.util.concurrent.ThreadLocalRandom; 022 023/** 024 * GNU libc crypt(3) compatible hash method. 025 * <p> 026 * See {@link #crypt(String, String)} for further details. 027 * <p> 028 * This class is immutable and thread-safe. 029 * 030 * @since 1.7 031 */ 032public class Crypt { 033 034 /** 035 * Encrypts a password in a crypt(3) compatible way. 036 * <p> 037 * A random salt and the default algorithm (currently SHA-512) are used. See {@link #crypt(String, String)} for 038 * details. 039 * </p> 040 * <p> 041 * A salt is generated for you using {@link ThreadLocalRandom}; for more secure salts consider using 042 * {@link SecureRandom} to generate your own salts and calling {@link #crypt(byte[], String)}. 043 * </p> 044 * 045 * @param keyBytes 046 * plaintext password 047 * @return hash value 048 * @throws IllegalArgumentException 049 * when a {@link java.security.NoSuchAlgorithmException} is caught. 050 */ 051 public static String crypt(final byte[] keyBytes) { 052 return crypt(keyBytes, null); 053 } 054 055 /** 056 * Encrypts a password in a crypt(3) compatible way. 057 * <p> 058 * If no salt is provided, a random salt and the default algorithm (currently SHA-512) will be used. See 059 * {@link #crypt(String, String)} for details. 060 * 061 * @param keyBytes 062 * plaintext password 063 * @param salt 064 * real salt value without prefix or "rounds=". The salt may be null, 065 * in which case a salt is generated for you using {@link ThreadLocalRandom}; 066 * for more secure salts consider using {@link SecureRandom} to 067 * generate your own salts. 068 * @return hash value 069 * @throws IllegalArgumentException 070 * if the salt does not match the allowed pattern 071 * @throws IllegalArgumentException 072 * when a {@link java.security.NoSuchAlgorithmException} is caught. 073 */ 074 public static String crypt(final byte[] keyBytes, final String salt) { 075 if (salt == null) { 076 return Sha2Crypt.sha512Crypt(keyBytes); 077 } else if (salt.startsWith(Sha2Crypt.SHA512_PREFIX)) { 078 return Sha2Crypt.sha512Crypt(keyBytes, salt); 079 } else if (salt.startsWith(Sha2Crypt.SHA256_PREFIX)) { 080 return Sha2Crypt.sha256Crypt(keyBytes, salt); 081 } else if (salt.startsWith(Md5Crypt.MD5_PREFIX)) { 082 return Md5Crypt.md5Crypt(keyBytes, salt); 083 } else { 084 return UnixCrypt.crypt(keyBytes, salt); 085 } 086 } 087 088 /** 089 * Calculates the digest using the strongest crypt(3) algorithm. 090 * <p> 091 * A random salt and the default algorithm (currently SHA-512) are used. 092 * </p> 093 * <p> 094 * A salt is generated for you using {@link ThreadLocalRandom}; for more secure salts consider using 095 * {@link SecureRandom} to generate your own salts and calling {@link #crypt(String, String)}. 096 * </p> 097 * 098 * @see #crypt(String, String) 099 * @param key 100 * plaintext password 101 * @return hash value 102 * @throws IllegalArgumentException 103 * when a {@link java.security.NoSuchAlgorithmException} is caught. 104 */ 105 public static String crypt(final String key) { 106 return crypt(key, null); 107 } 108 109 /** 110 * Encrypts a password in a crypt(3) compatible way. 111 * <p> 112 * The exact algorithm depends on the format of the salt string: 113 * <ul> 114 * <li>SHA-512 salts start with {@code $6$} and are up to 16 chars long. 115 * <li>SHA-256 salts start with {@code $5$} and are up to 16 chars long 116 * <li>MD5 salts start with {@code $1$} and are up to 8 chars long 117 * <li>DES, the traditional UnixCrypt algorithm is used with only 2 chars 118 * <li>Only the first 8 chars of the passwords are used in the DES algorithm! 119 * </ul> 120 * The magic strings {@code "$apr1$"} and {@code "$2a$"} are not recognized by this method as its output should be 121 * identical with that of the libc implementation. 122 * <p> 123 * The rest of the salt string is drawn from the set {@code [a-zA-Z0-9./]} and is cut at the maximum length of if a 124 * {@code "$"} sign is encountered. It is therefore valid to enter a complete hash value as salt to e.g. verify a 125 * password with: 126 * 127 * <pre> 128 * storedPwd.equals(crypt(enteredPwd, storedPwd)) 129 * </pre> 130 * <p> 131 * The resulting string starts with the marker string ({@code $n$}), where n is the same as the input salt. 132 * The salt is then appended, followed by a {@code "$"} sign. 133 * This is followed by the actual hash value. 134 * For DES the string only contains the salt and actual hash. 135 * The total length is dependent on the algorithm used: 136 * <ul> 137 * <li>SHA-512: 106 chars 138 * <li>SHA-256: 63 chars 139 * <li>MD5: 34 chars 140 * <li>DES: 13 chars 141 * </ul> 142 * <p> 143 * Example: 144 * 145 * <pre> 146 * crypt("secret", "$1$xxxx") => "$1$xxxx$aMkevjfEIpa35Bh3G4bAc." 147 * crypt("secret", "xx") => "xxWAum7tHdIUw" 148 * </pre> 149 * <p> 150 * This method comes in a variation that accepts a byte[] array to support input strings that are not encoded in 151 * UTF-8 but e.g. in ISO-8859-1 where equal characters result in different byte values. 152 * 153 * @see "The man page of the libc crypt (3) function." 154 * @param key 155 * plaintext password as entered by the used 156 * @param salt 157 * real salt value without prefix or "rounds=". The salt may be null, in which case a 158 * salt is generated for you using {@link ThreadLocalRandom}; for more secure salts 159 * consider using {@link SecureRandom} to generate your own salts. 160 * @return hash value, i.e. encrypted password including the salt string 161 * @throws IllegalArgumentException 162 * if the salt does not match the allowed pattern 163 * @throws IllegalArgumentException 164 * when a {@link java.security.NoSuchAlgorithmException} is caught. * 165 */ 166 public static String crypt(final String key, final String salt) { 167 return crypt(key.getBytes(StandardCharsets.UTF_8), salt); 168 } 169}