Password Encryption¶

1. Legacy Encrypted Password (Weak Encryption)¶

Legacy encrypted passwords use a fixed encryption method that produces the same encrypted value for identical passwords.

Characteristics: - Relatively short hex string - Even number of hex pairs (bytes) - Fixed encryption - same password always produces the same encrypted value - Less secure than newer methods

Example: .. code-block:: text

a00a51f9a161eebeda7a997117ddfeca

Generation: Use the mdsencryptpassword utility with the /legacy option:

mdsencryptpassword /legacy "YourPassword"

2. AES Encrypted Password¶

AES encrypted passwords use advanced encryption with random salting, providing enhanced security.

Characteristics: - Long hex string - Always starts with 01 - Odd number of hex pairs (bytes) - Each encryption produces a unique value, even for the same password - Cryptographically secure with proper salting

Example: .. code-block:: text

01c3f05c0ca0d7868adf16b133d8fe5ee820922805920dbeec8717cb07bc1b1c4264836c860105e717468f6191f2a814ac

Generation: Use the mdsencryptpassword utility with default settings:

mdsencryptpassword "YourPassword"

3. Windows Credentials Manager Entry Reference¶

Windows Credentials Manager references store passwords securely in the Windows Credential Manager system, with only a reference stored in the configuration file.

Characteristics: - Always starts with 02 - Length varies based on the entry name length - Hex-encoded reference to Windows Credential Manager entry - Username field in Credentials Manager is left blank (unused) - Actual username still stored as INT token in INT file

Example: .. code-block:: text

02636F6D2E6D6572746563682E67686768

Generation: Use the included PowerShell script with two parameters: - $TargetName - Name of the entry in Credentials Manager - $Password - Password to store

.\StoreCredential.ps1 -TargetName "MyDatabaseConnection" -Password "YourPassword"

The script will: 1. Store the password in Windows Credential Manager 2. Generate the hex reference string for use in configuration files

Basic Usage¶

mdsencryptpassword [options] <password>

Options¶

-legacy

Use legacy encryption method for backward compatibility with older BTR2SQL versions.

-help or -?

Display help information and usage instructions.

Examples¶

Encrypt a password using the new enhanced method:

mdsencryptpassword "MySecurePassword123"

Encrypt a password using legacy method:

mdsencryptpassword -legacy "MySecurePassword123"

Benefits¶

• System-Level Security: Passwords are protected by Windows security mechanisms

• No Plain Text Storage: Eliminates the need to store passwords in configuration files

• User-Specific Storage: Credentials are tied to the current Windows user account

• Centralized Management: Use Windows tools to manage stored credentials

PowerShell Script for Credential Storage¶

BTR2SQL includes a PowerShell script that automates the process of storing credentials in Windows Credential Manager and generating the corresponding reference string for configuration files.

Script Parameters:

$TargetName

The name of the entry in the Windows Credential Manager. This name will be used to identify the stored credential.

$Password

The password to store securely in the Credential Manager.

Script Functionality:

The PowerShell script performs the following operations:

1. Stores Credential: Uses Windows API calls to securely store the password in the Credential Manager

2. Generates Reference: Creates a hex-encoded reference string that starts with 02

3. Encodes Target Name: Converts the target name to ASCII bytes and ensures even length by appending a null byte if necessary

4. Creates Final Reference: Prepends 02 to the encoded target name and converts to hexadecimal

Usage Example:

# Store a database password
.\StoreCredential.ps1 -TargetName "ProductionDB" -Password "MySecurePassword123"

Output: The script will output both a success message and the hex reference string:

Credential stored successfully.
02506F64756374696F6E4442

Important Notes:

• The username field in Windows Credential Manager is left blank and unused

• The actual username is still stored as an INT token in the INT configuration file

• Credentials are stored with CRED_PERSIST_LOCAL_MACHINE persistence level

• The script uses CRED_TYPE_GENERIC credential type for maximum compatibility

Script as Reference Implementation:

The PowerShell script is provided as a reference implementation that you can use as-is or modify to suit your specific needs. You may wish to extend or customize the script to add additional credential management features such as:

• Entry editing and updating existing credentials

• Bulk credential operations for multiple database connections

• Integration with automated deployment pipelines

• Custom credential validation and verification

• Enhanced error handling and logging

• Integration with enterprise credential management systems

The script demonstrates the core Windows API calls and encoding logic needed to work with BTR2SQL’s credential reference system, making it a useful starting point for building more sophisticated credential management solutions.

Method 1: AES Encrypted Password (Recommended)¶

1. Generate AES Encrypted Password:

   mdsencryptpassword "YourDatabasePassword"
   

2. Update Configuration File:

   Use the encrypted value in your mds_global.ini or connection configuration:

   [Database]
   Password=01c3f05c0ca0d7868adf16b133d8fe5ee820922805920dbeec8717cb07bc1b1c4264836c860105e717468f6191f2a814ac
   

Method 2: Windows Credential Manager Reference¶

1. Store Credential Using PowerShell Script:

   .\StoreCredential.ps1 -TargetName "MyDatabaseConnection" -Password "YourDatabasePassword"
   

2. Update Configuration File:

   Use the generated reference string in your configuration:

   [Database]
   Password=02636F6D2E6D6572746563682E67686768
   

Method 3: Legacy Encrypted Password (Compatibility Only)¶

1. Generate Legacy Encrypted Password:

   mdsencryptpassword /legacy "YourDatabasePassword"
   

2. Update Configuration File:

   Use the encrypted value in your configuration:

   [Database]
   Password=a00a51f9a161eebeda7a997117ddfeca
   

Common Issues¶

“Invalid encrypted password” error

• Verify the encrypted password was generated correctly

• Ensure you’re not mixing legacy and new encryption methods

• Check that the password wasn’t corrupted during copy/paste

• Verify the password type matches the expected format:

  • Legacy: Even number of hex pairs, no prefix

  • AES: Starts with 01, odd number of hex pairs

  • Windows Credential Manager: Starts with 02

Connection failures after upgrading

• Re-encrypt existing passwords using the new utility

• Verify configuration file syntax is correct

• Test with a plain text password first to confirm connectivity

Legacy Password Issues

• Legacy passwords are case-sensitive in the hex representation

• Ensure the /legacy flag was used during generation

• Legacy passwords should be an even number of hex characters

AES Password Issues

• AES passwords must start with 01

• Verify the full hex string was copied without truncation

• Remember that AES passwords are longer than legacy passwords

Windows Credential Manager issues

• Ensure BTR2SQL is running with appropriate Windows permissions

• Verify credentials are stored under the correct Windows user account

• Check Windows Event Logs for credential access errors

• Confirm the PowerShell script completed successfully

• Verify the hex reference starts with 02

• Check that the target name in Credential Manager matches the reference

Password Type Identification

If you’re unsure which type of password you have:

• Legacy: Short, even number of hex pairs, no 01 or 02 prefix

• AES: Long, starts with 01, odd number of hex pairs

• Windows Credential Manager: Starts with 02, length varies by target name