Create Environment Variables within the Windows Operating System

To accommodate requirements for the ENH-607 enhancement to the BatchProcessor, a new BatchProcessing_Core.zip was created and distributed with Release 2.34.01 to allow encryption of the connectionString within the Windows environment variable used by the BatchProcessor for End of Day Processing.

The BatchProcessing_Core.zip file contains three files:

appsettings.json containing application configuration information
BatchProcessor.exe containing the batch processing application
nlog.config containing the logging configuration information

Once the required environment variables are created within the Windows operating system, the files contained within the BatchProcessing_Core.zip are extracted, and the configuration files are updated for your state's environment, the BatchProcessor.exe file can be run successfully from the Command Prompt.

NOTE: The BatchProcessor.exe is intended to be stored and run directly on the server in your state's environment.

The following are required to successfully run the BatchProcessor.exe from the Command Prompt to execute End of Day Processing and/or End of Month Processing:

The SPIRIT WIC system and database must be upgraded to Release 2.33.00 and above for End of Day Processing.
The SPIRIT WIC system and database must be upgraded to Release 2.38.00 and above for End of Month Processing.
Environment variables must be created in the Windows operating system on the server for each site that exists in your state's environment. For more information, see the Create Environment Variables within the Windows Operating System topic.
The BatchProcessor.exe file must be extracted from the BatchProcessing_Core.zip file. For more information, see the BatchProcessing_Core.zip Installation and Configuration topic.

With Release 2.34.01, the BatchProcessor also can perform the following tasks at the Command Prompt:

Encrypt the connectionString within an existing Windows environment variable that is currently used by BatchProcessor Processing.
Encrypt the connectionString and create a new Windows environment variable for BatchProcessor Processing.

The tutorial below outlines how to perform the following tasks:

Use the Command Prompt to encrypt the connectionString within an existing Windows environment variable that is currently used by BatchProcessor Processing.
Use the Command Prompt to encrypt the connectionString and create a new Windows environment variable for BatchProcessor Processing.

The steps in the tutorial below must be performed by a system administrator.

Complete the following steps to encrypt the connectionString within an existing Windows environment variable that is currently used by BatchProcessor Processing, or to encrypt the connectionString and create a new Windows environment variable for BatchProcessor Processing:

1. Log in or remotely connect as an administrator to the server in your state's environment.

2. Run the Command Prompt as an administrator. The Administrator: Windows Command Processor screen displays.

Administrator: Windows Command Processor window

NOTE: If the Windows Command Processor screen does not show "Administrator:" in the title bar text, then the Command Prompt is not running in administrator mode. The Command Prompt must be run as an administrator to successfully complete the steps in this tutorial.

3. Change the directory to the folder in which the contents of the BatchProcessing_Core.zip were extracted. See Step 4 of the BatchProcessing_Core.zip Installation and Configuration topic for more information.

4. Once focus at the Command Prompt is placed in the folder in which the contents of the BatchProcessing_Core.zip were extracted, enter the following command with the connectionString values containing the settings specific to the SPIRIT database instance to be used in your state's environment in the format below and press the Enter key on your keyboard.

BatchProcessor.exe -setConnectionString "[connectionString]" [CN]

NOTE: In the command above, the [connectionString] attribute identifies the connectionString containing the server, database, login credentials, and other parameters used by the Windows environment variable for your state's environment.

An example of a [connectionString] is as follows:

Server=[Server Name];Database=[Database Name];User ID=[User ID];Password=[Password];Persist Security Info=True;MultipleActiveResultSets=True;

NOTE: In the connectionString example above, the following are variables that are unique to your state's environment:

[Server Name] is the name of the server that hosts database services in your state's environment.
[Database Name] is the identification of the database instance on the server in your state's environment.
[User ID] is the user identification used to access the database instance on the server in your state's environment.
[Password] is the password used to access the database instance on the server in your state's environment.

NOTE: In the command above, the [CN] attribute identifies the [State Identifier Code] attribute specified in the Windows environment variable for your state's environment.

For example, the [Server Name], [Database Name], [User ID], and [Password] connectionString values for the Chickasaw Nation's WIC program might be as follows:

Server=WSRVCOCN;Database=WSPCOCN;User ID=SYSTEM.ADMIN;Password=P@ssw0rd123;Persist Security Info=True;MultipleActiveResultSets=True;

When the command is executed and an error occurred, the Command Prompt identifies and displays the error(s) that occurred.

Administrator: Windows Command Processor screen - BatchProcessor.exe -setConnectionString "[connectionString]" [CN] (configuration error)

5. If an error occurred, press any key on your keyboard to continue and repeat Step 4 above using a valid connectionString. Otherwise, complete the remaining steps in this tutorial.

6. Once the connectionString entered is validated, the Command Prompt prompts for the entry of a password to create an AES derived key.

Administrator: Windows Command Processor screen - password prompt for AES derived key creation

7. Enter a password to create an AES derived key.

NOTE: Any password can be used to create the AES derived key. The password is only used to create the AES derived key and it is not needed again for verification purposes. However, a Windows environment variable can only hold a maximum of 32767 characters. The connectionString is stored in the Windows environment variable in a single environment block. 32767 characters is the sum of all environment variable names and values and the connectionString.

Enter a shorter password to ensure that the encrypted connectionString does not exceed the maximum number of characters allowed in environment block within the Windows environment variable.

The password provided is hashed using SHA384 algorithms and randomly-generated salt bytes. The iterations, which default to 1000, are passed as Rfc2898DeriveBytes to generate the AES derived key and AES IV with default key and block sizes.

Rfc2898DeriveBytes implements the password-based on PBKDF2 key derivation functionality, which applies a pseudorandom function (HMAC), to the password along with a salt value and repeats the process many times to produce an AES key.

The AES key and AES IV are merged and protected using CNG DPAPI. CNG DPAP enables secure share keys, passwords, key materials, and messages by protecting them with a set of principals to a data protection scope set to machine.

The DPAPI protect method uses an optional entropy and data protection scope. The code generates random bytes for the Entropy and sets the data protection scope to the LocalMachine. The LocalMachine enumeration value is used in server-specific applications that run on a server where users that are not trusted are not allowed access.

The DPAPI protect method returns the protected Key and protected entropy, which are then merged as the encrypted string returned by the AES encryption, and then stored as the following Windows environment variable:

BatchProcessor: [State Identifier Code]:SpiritDatabase

8. Once the password is entered, press the press the Enter key on your keyboard. The Command Prompt encrypts the existing or creates the new Windows environment variable and prompts for a keypress.

Administrator: Windows Command Processor screen - connectionString encryption and/or Windows environment variable creation complete

9. Press any key on your keyboard to exit the -setConnectionString process.

10. Multiple sites or agencies may be hosted by the server in your state's environment. For example, the Oklahoma Indian Tribal Organizations (ITOs) are multiple agencies served by a single file server and each agency has its own database in a single server environment. If your environment's server hosts multiple databases for multiple sites or agencies, an environment variable must be created for each site or agency that the server in your environment hosts. Repeat the steps in this exercise to create an environment variable for each database.

NOTE: After encrypting the connectionString within an existing Windows environment variable that is currently used by BatchProcessor Processing, or when encrypting the connectionString and creating a new Windows environment variable for BatchProcessor Processing, a reboot may be required.

11. Close the Command Prompt screen.

Software Version: 2.40.00

Updated in Rel 2.40 per SWEB US 152726