Return to HomePage

Code Example Schema (Template)

* Title
* Applies To
* Summary
* Contents
* Objectives
* Scenarios
* Solution Example
* Problem Example
* Test Case
* Expected Result
* Additional Resources
* Attributes

Code Example Schema (Template explained and test cases)

Title

<< Insert title that resonates from a findability perspective.>>

Test Cases:
* Does the title distinguish by product or version where possible?
* _Does the title distinguish it from related examples? _
* If technology is in the title, is the version included?
* Are important nouns a user might scan for towards the left of the title?

Applies To

<< Identify the most directly relevant product or technologies this information applies to >>

Test Cases:
* Is it clear what technologies or products this applies to?
* Conversely, is it clear what technologies of products this does not apply to?

Summary

<< Insert 3-5 lines max description of the intent of the code example, highlighting when to use and key scenarios.>>

Test Cases:
* _Does the description crisply summarize the solution? _
* Is the intent of the code clear?

Objectives

<< Insert bulleted list of task-based outcomes for the code example. Identify the user objectives for choosing this code. Identify the intent of the code. >>

Test Cases
* Are the user objectives for choosing this code identified?
* Are the objectives of the code identified?
* When would a user need this code example?
* Is it clear why the solution example is preferred over the problem example?

Scenarios

<< Insert a bulleted list of example usage scenarios you have seen this code used in practice.>>

Test Cases
* Are the example scenarios based on real solutions seen in practice?
* Do the example scenarios help highlight when to use the code or when not to?

Solution Example

<< Insert commented code illustrating the solution. Insert code example as a blob within a function. The blob allows quick reading of the code. It also allows quickly testing from a function, inlining within other code, or refactoring for a given context. The alternative is to factor up front, but this increases complexity and can negatively impact consumption. This leaves refactoring to the developer for their given scenario.>>

Test Cases:
* Is the code example organized as a blob within a function that can easily be tested or refactored?
* Do the comments add insights around decisions?
* Are the comments concise enough so they don't break the code flow?

Problem Example

<< Insert commented code illustrating issues. List examples of common mistakes along with issues.>>

Test Cases:
* Are comments concise enough so that they does not break the code flow?
* _Are the mistakes clear? _
* Are the patterns and variations of the problems clear?

Test Case

<< Insert relevant setup information. Write the code to call the functional blob from Solution Example.>>

Test Cases:
* Is setup Information included?
* Does the example call the functional blob in the Solution example?
* Can you copy+paste the code and execute it?

Expected Result

<< Insert what you expect to see when running the test case. >>

Test Cases:
* If you run the Test Case, do the Expected Results match?

More Information

<<Optional. Insert more information as necessary. This could be background information or interesting additional details.>>

Additional Resources

<< Optional. Insert bulleted list of descriptive links to resources that have direct value or relevancy.>>

Test Cases:
* _The links starts with the pattern "For more information on X, see ..."? _
* The links are directly relevant versus simply nice to have?

Attributes

<< Insert the following:
* Applies To
* Category
* Author
>>

Example

Hash a Password Using a Random Salt (C#)

Applies To

* ASP.NET 2.0
* C#

Summary

The purpose of this code snippet is to demonstrate how to implement secure password persistence using a cryptographic hashing algorithm with a randomly generated "salt" (or "nonce") value. Cryptographic hashing algorithms are one-way encryption algorithms used to store sensitive data in a non-readable format. A salt can be used in conjunction with cryptographic hashing to add additional entropy to encrypted values and to protect against pre-computed hash or dictionary attacks on a compromised hash value.

Objectives

* Protect user credentials
* Avoid storing user passwords
* Protect against certain brute-force attacks on a compromised hash value
* Generate a cryptographically random value for the salt that cannot be predicted
* Add enough entropy to the password hash to increase the difficulty of a cracking attempt exponentially

Scenarios

* Application makes use of a dedicated user account management system and stores passwords
* Application stores a "Secret Question/Answer" credential for password reset operations
* Application requires storage of highly sensitive data (social security number, credit card number, etc) but does not need to retrieve that data

Solution Example

public static byte[] CreatePasswordHash(string password)
{

		    	// Convert the string password value to a byte array
		    	byte[] passwordData = [UnicodeEncoding.ASCII.GetBytes(password);]

		    	// Create a 4-byte salt using a cryptographically secure random number generator
		    	byte[] saltData = new byte[4];
		    	[RNGCryptoServiceProvider] rng = new [RNGCryptoServiceProvider();]
		    	[rng.GetNonZeroBytes(saltData);]

		    	// Append the salt to the end of the password
		    	byte[] [saltedPasswordData] = new byte[passwordData.Length + saltData.Length];
		    	Array.Copy(passwordData, 0, [saltedPasswordData,] 0, passwordData.Length);
		    	Array.Copy(saltData, 0, [saltedPasswordData,] passwordData.Length, saltData.Length);

		    	// Create a new SHA-1 instance and compute the hash 
		    	SHA1Managed sha = new SHA1Managed();
		    	byte[] hashData = [sha.ComputeHash(saltedPasswordData);]

		    	// Optional - add salt bytes onto end of the password hash for storage
		    	bool APPEND_SALT_TO_HASH = true;

		    	if (APPEND_SALT_TO_HASH)
		    	{
		        		byte[] [hashSaltData] = new byte[hashData.Length + saltData.Length];
		        		Array.Copy(hashData, 0, [hashSaltData,] 0, hashData.Length);
		        		Array.Copy(saltData, 0, [hashSaltData,] hashData.Length, saltData.Length);
		        		return [hashSaltData;]
		    	}
		    	else
		    	{
		        		return hashData;
		    	}

}

Problem Example

The following code snippet shows password hashing without the use of a salt and using a weaker hashing algorithm.

// password is obtained from the user as a C# string
string password = Request.Form"password";

// Convert the string password value to a byte array
byte[] passwordData = UnicodeEncoding.ASCII.GetBytes(password);

// Create a new MD5 instance and compute the hash
MD5CryptoServiceProvider md5 = new MD5CryptoServiceProvider();
byte[] hashData = md5.ComputeHash(passwordData);

* Hash values are vulnerable to pre-computed hash attacks
* Depending on password value, password hash may also be vulnerable to a dictionary attack
* MD5 offers less encryption strengtgh than SHA-1 and has recently been "broken" by cryptography researchers

Test Case

The following classes must be included in any project making use of the sample code provided above:

using System.Security.Cryptography;

Execute a test encryption and comparison of a salted password hash using the following test case methods:

static void Main(string[] args)
{

		    	// Create a Hash and compare to two subsequent hashes
		    	byte[] hash = CreatePasswordHash("foobar");
		    	Console.WriteLine("\nCreated new salted hash for 'foobar'");            
		    	Console.WriteLine("foobar produces same hash:\t" + ComparePasswordToHash("foobar", [hash).ToString());]
		    	Console.WriteLine("fo0bar produces same hash:\t" + ComparePasswordToHash("f0obar", [hash).ToString());]

}

public static bool ComparePasswordToHash(string password, byte[] hashData)
{

		    	// First, pluck the four-byte salt off of the end of the hash
		    	byte[] saltData = new byte[4];
		    	Array.Copy(hashData, hashData.Length - saltData.Length, saltData, 0, saltData.Length);

		    	// Convert Password to bytes
		    	byte[] passwordData = [UnicodeEncoding.ASCII.GetBytes(password);]

		    	// Append the salt to the end of the password
		    	byte[] [saltedPasswordData] = new byte[passwordData.Length + saltData.Length];
		    	Array.Copy(passwordData, 0, [saltedPasswordData,] 0, passwordData.Length);
		    	Array.Copy(saltData, 0, [saltedPasswordData,] passwordData.Length, saltData.Length);

		    	// Create a new SHA-1 instance and compute the hash 
		    	SHA1Managed sha = new SHA1Managed();
		    	byte[] [newHashData] = [sha.ComputeHash(saltedPasswordData);]

		    	// Add salt bytes onto end of the password hash for storage
		    	byte[] [newHashSaltData] = new byte[newHashData.Length + saltData.Length];
		    	[Array.Copy(newHashData,] 0, [newHashSaltData,] 0, [newHashData.Length);]
		    	Array.Copy(saltData, 0, [newHashSaltData,] [newHashData.Length,] saltData.Length);

		    	// Compare and return
		    	return [(Convert.ToBase64String(hashData).Equals(Convert.ToBase64String(newHashSaltData)));]

}

Expected Result

Created new salted hash for 'foobar'
foobar produces same hash: True
fo0bar produces same hash: False

More Information

Password hash and salt values should always be securely protected in storage. An attacker able to compromise a specific hash and salt value from a database may succeed in using other types of brute-force attacks against the compromised hash.

In the example given, the four-byte salt would require an attacker to maintain 4.3 trillion values for every given plaintext value. Assuming the victim required passwords of only 4 alphabetical characters in
length with no other complexity requirements (a very weak password policy by our standards), defeating a four-byte salt would require the attacker to have a database of 2 x 10^15 precomputed hashes handy. Assuming each of these hashes only required one byte to store, this would require 2 petabytes of storage.

Additional Resources

* See "Cryptopgraphy" section in "Security Guidelines: .NET Framework 2.0" at http://msdn.microsoft.com/library/en-us/dnpag2/html/PAGGuidelines0003.asp?frame=true#pagguidelines0003_cryptography