Microsoft KB Archive/313091

Knowledge Base

How to create keys by using Visual Basic .NET for use in Forms authentication

Article ID: 313091

Article Last Modified on 10/29/2007

---

APPLIES TO

• Microsoft ASP.NET 1.0
• Microsoft Visual Basic .NET 2002 Standard Edition
• Microsoft ASP.NET 1.1
• Microsoft Visual Basic .NET 2003 Standard Edition

---

This article was previously published under Q313091

For a Microsoft Visual C# .NET version of this article, see 312906.

This article refers to the following Microsoft .NET Framework Class Library namespaces:

• System.Text
• System.Security.Cryptography

IN THIS TASK

SUMMARY

• Requirements
• Create the project
• Write the code to hash a password
• Generate the hashes
• Update the configuration file
• Troubleshooting

REFERENCES

SUMMARY

This article describes how to create keys to use for encryption, decryption, and validation of Forms authentication cookie data. You can use the keys that you create in this article for the validationKey and the decryptionKey attributes of the <machineKey> section in the <system.web> element in the Machine.config and the Web.config files.

back to the top

Requirements

The following list outlines the recommended hardware, software, network infrastructure, and service packs that you need:

• Microsoft Windows 2000 or Microsoft Windows XP
• Microsoft .NET Framework
• Microsoft Internet Information Services (IIS)

back to the top

Create the project

1. Start Microsoft Visual Studio .NET.
2. On File menu, point to New, and then click Project.
3. In the Project Types area, click Visual Basic Projects.
4. In the Templates area, click Console Application.
5. In the Name text box, type HashConfigVb, and then click OK.

back to the top

Write the code to hash a password

The code in this section reads two arguments that are passed from the command line:

• The first argument is the number of bytes that is used to create the decryptionKey attribute.
• The second argument is the number of bytes that is used to create the validationKey attribute.

The code uses a random number generator to create a random number of bytes based on the command-line arguments. After the random bytes are created, the bytes are formatted into a hexadecimal string that is suitable for use in the .config files.

Note The hexadecimal string that is created is twice the size of the value that is passed on the command line. For example, if you specify 24 bytes for a key, the resulting string is 48 bytes in length after the conversion. The valid values for decryptionKey is 8 or 24. This creates a 16 byte key for Data Encryption Standard (DES) or a 48 byte key for Triple DES, respectively. Valid values for validationKey are 20 to 64. This creates keys from 40 to 128 bytes in length after the conversion. The output from the code is an entire <machineKey> element that you can copy and paste into a Machine.config or a Web.config file.

1. Add a new class file named KeyCreator to your Visual Basic project.

2. Replace the existing code in the KeyCreator.vb file with the following code:

   Imports System
   Imports System.Text
   Imports System.Security.Cryptography
   
   Namespace Crypto
     Public Class KeyCreator
       
       Public Shared Sub CreateMachineKey()
         Dim commandLineArgs As String()
         commandLineArgs = System.Environment.GetCommandLineArgs()
   
         Dim decryptionKey As String
         decryptionKey = CreateKey(System.Convert.ToInt32(commandLineArgs(1)))
         Dim validationKey As String
         validationKey = CreateKey(System.Convert.ToInt32(commandLineArgs(2)))
   
         Console.WriteLine("<machineKey validationKey=""{0}"" decryptionKey=""{1}"" validation=""SHA1""/>", _
         validationKey, decryptionKey)
        End Sub
   
        Public Shared Function CreateKey(numBytes As Integer) As String
          Dim rng As RNGCryptoServiceProvider = New RNGCryptoServiceProvider()
          Dim buff(numBytes -1) As Byte
   
          rng.GetBytes(buff)
                   
          Return BytesToHexString(buff)
        End Function
    
        Public Shared Function BytesToHexString(bytes As Byte()) As String
          Dim hexString As StringBuilder = New StringBuilder(64)
          Dim counter as Integer
   
          For counter = 0 To bytes.Length - 1
            hexString.Append(String.Format("{0:X2}", bytes(counter)))
          Next
   
          Return hexString.ToString()
       End Function
   
     End Class
   End Namespace
                       

3. Open the Module1.vb file that is created by default, and then add the following code in the Main sub routine:

       Dim MyKeyCreator As New Crypto.KeyCreator()
       MyKeyCreator.CreateMachineKey()
                       

4. Build the application.

back to the top

Generate the hashes

Run the application from a command prompt, and then pass in two integer values that are the size of the decryption and the validation keys. If you named the console application HashConfigVb.exe, type the following syntax at the command prompt in the Bin directory of the application:

HashConfigVb.exe 24 64

The application should return output that is similar to the following output:

<machineKey validationKey="08CE6B478DCE73..........E566D8AC5D1C045BA60"
            decryptionKey="4252D6B2268.........67F451CE65D0F2ABE9BCD3A"
            validation="SHA1"/>
                    

Note Because the code uses a random number generator, the output is different each time.

back to the top

Update the configuration file

1. Locate the Machine.config or the Web.config file.
2. Locate the <system.web> section in the configuration file.
3. Replace the <machineKey> section with the output from the console application. If the <machineKey> section does not exist, create it.
4. Save the configuration file.
5. Restart IIS on all servers in the Web farm for the Machine.config changes to take effect.

back to the top

Troubleshooting

Make sure that the <machineKey> section has identical, explicit keys (that is, do not use the AutoGenerate option for attributes in the <machineKey> section) across the Web farm in the following scenarios:

• When you use Forms authentication.
• When you run session state in StateServer mode.
• When you want ViewState to be available across a Web farm because the enableViewStateMAC attribute is set to True by default.

back to the top

REFERENCES

For additional information, click the following article numbers to view the articles in the Microsoft Knowledge Base:

308157 How to implement forms-based authentication in your ASP.NET application by using Visual Basic .NET

306238 How to implement role-based security with Forms-based authentication in your ASP.NET application by using Visual Basic .NET

306590 INFO: ASP.NET security overview

307626 INFO: ASP.NET configuration overview

back to the top

Additional query words: webfarm view state

Keywords: kbproductlink kbconfig kbhowtomaster kbsecurity kbstate KB313091

---

Send feedback to Microsoft

© Microsoft Corporation. All rights reserved.