Code Example Template

From Guidance Share

Contents 1 Template 2 Test Cases 2.1 Title 2.2 Applies To 2.3 Summary 2.4 Objectives 2.5 Scenarios 2.6 Solution Example 2.7 Problem Example 2.8 Test Case 2.9 Expected Result 2.10 More Information 2.11 Additional Resources 2.12 Attributes 3 Example 3.1 Hash a Password Using a Random Salt (C#) 3.2 Applies To 3.3 Summary 3.4 Objectives 3.5 Scenarios 3.6 Solution Example 3.7 Problem Example 3.8 Test Case 3.9 Expected Result 3.10 More Information 3.11 Additional Resources 3.12 Attributes

Template

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

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

Attributes

• Applies To: .NET Framework 2.0, C#
• Category: Cryptography
• Author: Jonathan Bailey