Page History

Any time an application stores a password as cleartext (unencrypted text data), its value is potentially exposed in a variety of ways. To prevent this information from being inadvertently leaked, this exposure must be limited. While a program will receive the password from the user as cleartext, this should be the last time it is in this form.

_Hash functions_ allow programs to indirectly compare an input password to the original, without storing a cleartext or decryptable version of the password. This approach minimizes the exposure of the password without presenting any practical disadvantages.

h2. Cryptographic Hash Functions

The value that a hash function outputs is called the _hash value_. Another term for hash value is _message digest_. Hash functions are computationally feasible functions whose inverses are computationally infeasible. This means that in practice, one can encode a password to a hash value, while they are also unable to decode it. The equality of the passwords can be tested through the equality of their hash values.

Java's {{MessageDigest}} class provides the functionality of various cryptographic hash functions. Be careful not to use any defective hash functions, such as _MD5_. {color:red}How do I go about learning which hash functions are safe, and which are defective?{color}

It is also important that you append a _salt_ to the password you are hashing. A salt is a randomly generated piece of data that is stored along with the hash value. The use of a salt helps prevents dictionary attacks against the hash value, provided the salt is long enough {color:red}what is long enough{color} . Each password should have its own salt associated with it. If a single salt were used for more than one password, two users would be able to see if their passwords are the same.

h2. Noncompliant Code Example

This noncompliant code example encrypts and decrypts the password stored in {{credentials.pw.}}

{code:bgColor=#FFcccc}
public final class Password {
  private void setPassword(byte[] pass) throws Exception {
    // Arbitrary encryption scheme
     bytesbyte[] encrypted = encrypt(pass); //arbitrary encryption scheme
    clearArray(pass);      
    saveBytes(encrypted,"password.bin"); //encrypted Encrypted password to password.bin
    saveBytes(encrypted,"password.bin");
    clearArray(encrypted); 
  }

  private boolean checkPassword(byte[] pass) throws Exception {
    // Load the boolean arrays_equal;encrypted password
    byte[] encrypted = loadBytes("password.bin"); //load the encrypted password
    byte[] decrypted = decrypt(encrypted);
    arrays_equalclearArray(encrypted);
    boolean arraysEqual = Arrays.equal(decrypted, pass);
    clearArray(decrypted);
    clearArray(pass);
    return arrays_equalarraysEqual;
  }

  private void clearArray(byte[] a) {
    for //set all of the elements in a to zero
  }
}
{code}


An attacker could potentially decrypt this file to discover the password. This attacker could be someone knows or has figured out the encryption scheme being used by the program.

h2. Noncompliant Code Example

This noncompliant code examples implements the {{SHA-1}} hash function through the {{MessageDigest}} class to compare hash values instead of cleartext strings.

{code:bgColor=#FFcccc}
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

public final class Password {
  private void setPassword(String pass) throws Exception {
    byte[] salt = generateSalt(12);
    MessageDigest sha_1 = MessageDigest.getInstance("SHA-1");
    byte[] hashVal = sha_1.digest((pass+salt).getBytes()); //encode the string and salt
    saveBytes(salt, "salt.bin");
    saveBytes(hashVal,"password.bin"); //save the hash value to credentials.bin
  }

  private boolean checkPassword(String pass) throws Exception {
    byte[] salt = loadBytes("salt.bin");
    MessageDigest sha_1 = MessageDigest.getInstance("SHA-1");
    byte[] hashVal1 = sha_1.digest((pass+salt).getBytes()); //encode the string and salt
    byte[] hashVal2 = loadBytes("password.bin"); //load the hash value stored in password.bin
    return Arrays.equals(hashVal1, hashVal2);
  }

  private byte[] generateSalt(int n) {
    //Generate a random byte array of length n
  }
}
{code}

Even if an attacker knows that the program stores passwords using {SHA-1} and a 12 byte salt, they will be unable to get the value of the password from {password.bin} and {salt.bin}. While this fixes the decryption problem from the previous noncompliant code example, at runtime this code may inadvertently store the passwords as cleartext. This is because the {{pass}} arguments may not be cleared from memory by the Java garbage collector. See [MSC10-J. Limit the lifetime of sensitive data|MSC10-J. Limit the lifetime of sensitive data] for more information.

h2. Compliant Solution

This compliant solution addresses the problems from the previous noncompliant examples.

{code:bgColor=#ccccff}
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

public final class Password {

  private void setPassword(byte[] pass) throws Exception {
    byte[] salt = generateSalt(12);
    byte[] input = appendArrays(pass, salt);
    MessageDigest sha_1 = MessageDigest.getInstance("SHA-1");
    byte[] hashVal = sha_1.digest(input); //encode the string and salt    
    clearArray(pass);    
    clearArray(input);
    saveBytes(salt, "salt.bin");    
    saveBytes(hashVal,"password.bin"); //save the hash value to credentials.pw
  }

  private boolean checkPassword(byte[] pass) throws Exception {
    byte[] salt = loadBytes("salt.bin");
    byte[] input = appendArrays(pass, salt);
    MessageDigest sha_1 = MessageDigest.getInstance("SHA-1");
    byte[] hashVal1 = sha_1.digest(input); //encode the string and salt
    clearArray(pass);
    clearArray(input);
    byte[] hashVal2 = loadBytes("credentials.pw"); //load the hash value stored in credentials.pw
    return Arrays.equals(hashVal1, hashVal2);
  }

  private byte[] generateSalt(int n) {
    //Generate a random byte array of length n
  }

  private byte[] appendArrays(byte[] a, byte[] b) {
    //Return a new array of a appended to b
  }

  private void clearArray(byte[] a) {
    //set all of the elements in a to zero
  }
}
{code}

In both the {{setPassword()}} and {{checkPassword()}} methods, the cleartext representation of the password is erased as soon as it is converted into a hash value. After this happens, there is no way for an attacker to get the password as cleartext. 

h2. Exceptions

*MSC18-EX0* Applications such as password managers may need to retrieve the original password in order to enter it into a third-party application. This is okay even though it violates the guideline. The difference here is that the password manager is accessed by a single user. The program will always have the user's permission to store their passwords in this way. Therefore, provided the user is competent, the program's operation will be safe. 

h2. Risk Assessment

Violations of this rule have to be manually detected because it is a consequence of the overall design of the password storing mechanism. It is pretty unlikely, since it will occur around once or twice in a program that uses passwords. As demonstrated above, almost all violations of this rule have a clear exploit associated with them.

|| Rule || Severity || Likelihood || Remediation Cost || Priority || Level ||
| MSC18-J | medium | likely | high | {color:#cc9900}{*}P6{*}{color} | {color:#cc9900}{*}L2{*}{color} |

h2. Bibliography

\[[API 2006|AA. Bibliography#API 06]\] Class {{java.security.MessageDigest}}

[http://www.javapractices.com/topic/TopicAction.do?Id=216] Passwords never in clear text(int i = 0; i < a.length; i++) {
      a[i] = 0;
    }
  }

  private byte[] encrypt(byte[] clearValue) {
    // ... symmetric encryption of clearValue bytes, returning the encrypted value
  }

  private byte[] decrypt(byte[] encryptedValue) {
    // ... symmetric decryption of  encryptedValue bytes, returning clear value
  }

  private void saveBytes(byte[] bytes, String filename) throws IOException {
    // ... write bytes to the file
  }
  
  private byte[] loadBytes(String filename) throws IOException { 
    // ... read bytes to the file 
  }
}

import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

public final class Password {
  private SecureRandom random = new SecureRandom();

  private void setPassword(String pass) throws Exception {
    byte[] salt = new byte[12];
    random.nextBytes(salt);
    MessageDigest msgDigest = MessageDigest.getInstance("SHA-256");
    // Encode the string and salt
    byte[] hashVal = msgDigest.digest((pass+salt).getBytes());
    saveBytes(salt, "salt.bin");
    // Save the hash value to password.bin
    saveBytes(hashVal,"password.bin");
  }

  boolean checkPassword(String pass) throws Exception {
    byte[] salt = loadBytes("salt.bin");
    MessageDigest msgDigest = MessageDigest.getInstance("SHA-256");
    // Encode the string and salt
    byte[] hashVal1 = msgDigest.digest((pass+salt).getBytes());
    // Load the hash value stored in password.bin
    byte[] hashVal2 = loadBytes("password.bin");
    return Arrays.equals(hashVal1, hashVal2);
  }

  private void saveBytes(byte[] bytes, String filename) throws IOException {
    // ... write bytes to the file
  }   

  private byte[] loadBytes(String filename) throws IOException { 
    // ... read bytes to the file 
  }
}

import java.security.GeneralSecurityException;
import java.security.SecureRandom;
import java.security.spec.KeySpec;
import javax.crypto.SecretKeyFactory;
import javax.crypto.spec.PBEKeySpec;
  
final class Password {
  private SecureRandom random = new SecureRandom();
  private final int SALT_BYTE_LENGTH = 12;
  private final int ITERATIONS = 100000;
  private final String ALGORITHM = "PBKDF2WithHmacSHA256";
    
  /* Set password to new value, zeroing out password */
  void setPassword(char[] pass)
      throws IOException, GeneralSecurityException  {
    byte[] salt = new byte[SALT_BYTE_LENGTH];
    random.nextBytes(salt);
    saveBytes(salt, "salt.bin");    
    byte[] hashVal = hashPassword(pass, salt); 
    saveBytes(hashVal,"password.bin");
    Arrays.fill(hashVal, (byte) 0);
  }

  /* Indicates if given password is correct */
  boolean checkPassword(char[] pass)
      throws IOException, GeneralSecurityException  {
    byte[] salt = loadBytes("salt.bin");
    byte[] hashVal1 = hashPassword(pass, salt);
    // Load the hash value stored in password.bin
    byte[] hashVal2 = loadBytes("password.bin");
    boolean arraysEqual = timingEquals(hashVal1, hashVal2);
    Arrays.fill(hashVal1, (byte) 0);
    Arrays.fill(hashVal2, (byte) 0);
    return arraysEqual;
  }
  
  /* Encrypts password & salt and zeroes both */
  private byte[] hashPassword(char[] pass, byte[] salt)
      throws GeneralSecurityException {
    KeySpec spec = new PBEKeySpec(pass, salt, ITERATIONS);
    Arrays.fill(pass, (char) 0);
    Arrays.fill(salt, (byte) 0);
    SecretKeyFactory f = SecretKeyFactory.getInstance(ALGORITHM);
    return f.generateSecret(spec).getEncoded();
  }

  /**
   * Indicates if both byte arrays are equal
   * but uses same amount of time if they are the same or different
   * to prevent timing attacks
   */
  public static boolean timingEquals(byte b1[], byte b2[]) {
    boolean result = true;
    int len = b1.length;
    if (len != b2.length) {
      result = false;
    }
    if (len > b2.length) {
      len = b2.length;
    }
    for (int i = 0; i < len; i++) {
      result &= (b1[i] == b2[i]);
    }
    return result;
  }

  private void saveBytes(byte[] bytes, String filename) throws IOException {
    // ... write bytes to the file
  }

  private byte[] loadBytes(String filename) throws IOException {
    // ... read bytes to the file
  }
}