Skip Ribbon Commands
Skip to main content

Ondrej Sevecek's English Pages

:

Engineering and troubleshooting by Directory Master!
MCM: Directory

Quick Launch

Ondrej Sevecek's English Pages > Posts > SharePoint passphrase internals
November 15
SharePoint passphrase internals

SharePoint uses the so-called passphrase to protect sensitve information in its configuration databases. This includes managed account passwords (Get-SPManagedAccount, New-SPManagedAccount) and also private key of the internal SharePoint root certification authority (CA) - SharePoint Root Authority. Indirectly, it is used to protect other sensitive passwords such as for non-managed accounts for various services such as Search and User Profile Service (UPS) and Secure Store service data.

When you install the first SP farm member and provision the configuration database, you must supply the passphrase. You either type it into the GUI SharePoint Products Configuration Wizard, or you can do it with PowerShell commandlet New-SPConfigurationDatabase.

When you connect another farm member to an existing configuration database, you must also supply the correct passphrase, again during the SPCW wizard or with the shell's Connect-SPConfigurationDatabase cmdlet.

You should keep the passphrase safely stored somewhere in order to be able to perform farm recovery, that is to restore the configuration database, and also to be able to connect additional farm member servers later.

The passphrase is stored permanently in registry of each farm member server where it is protected by DPAPI with the LocalMachine protection scope. Thus any process running on any farm member server have direct access to the passphrase. The registry key containing the DPAPI protected passphrase can be found here (just replace your current version number in the key name):

HKLM\Software\Microsoft\Shared Tools\Web Server Extensions\14.0\Secure\FarmAdmin
HKLM\Software\Microsoft\Shared Tools\Web Server Extensions\15.0\Secure\FarmAdmin
CredentialKeyDPEnt = REG_BINARY

Actually, the protected data do not store clear-text passphrase itself as you typed it during installation. The registry actually store a derived AES 256 bit key which is generated from the passphrase by simply hashing it with SHA512 and trimming the resulting 512bit hash to the first 256bits. The process simply takes only the first 32 Bytes of the SHA512 of the clear-text passphrase. You cannot ever obtain the clear-text passphrase from registry. You can only extract its respective AES 256 encryption key used to actually encrypt the sensitive configuration database information.

The configuration database is in turn encrypted/decrypted with the AES 256 key instead of the clear-text password to provide some better entropy for the encryption process.

As a matter of documenting the algorithm, jf you want to compute the SharePoint AES 256 bit key from a passphrase, you can use the following PowerShell script

$passphrase = 'Pa$$w0rd'
$sha512 = New-Object System.Security.Cryptography.Sha512CryptoServiceProvider
[byte[]] $passphraseBytes = [System.Text.Encoding]::Unicode.GetBytes($passphrase)
[BitConverter]::ToString($sha512.ComputeHash($passphraseBytes)[0..31])

If you do not know the current passphrase, you can reset it to some new value with Set-SPPassPhrase. In order to do this, you must have a running farm member server on which the stored passphrase is correct. The reason is because the Set-SPPassPhrase must obtain the current passphrase (actually rather the AES key) from registry, unprotect (decrypt) it with DPAPI, and decrypt the configuration database and encrypt it again with the new AES 256 key derived fromt the new passphrase. Finally it updates the registry value CredentialKeyDPEnt with the newly derived AES key protected with DPAPI.

The Set-SPPassPhrase cmdlet does not need anything else than local registry access and the configuration database access. The DPAPI must also work which means the operating system itself must work well. The SharePoint services, such as the SharePoint Timer (SPTimerV4, owstimer.exe) service or the SharePoint Administration (SPAdminV4, wssadmin.exe) service do not need to be running or working at all. So only the currently stored passphrase (the AES 256 key) must be correct against the configuration database.

So normally, the Set-SPPassphrase cmdlet re-encrypts the configuration database using the current and the new AES key and updates the local registry value CredentialKeyDPEnt. It extracts the assumed current passphrase from local registry automatically. You cannot supply the current passphrase manually.

If you have some farm member servers which do not have correct AES key (the passphrase) in their local registry - such as in case of operating system restore or some other failure situation - you can call the Set-SPPassphrase command with -LocalServerOnly switch parameter. In order to do this, you must know what current passphrase you want the command to update locally. This switch prevents configuration database re-encryption and only updates the local registry with whatever passphrase you specify.

How to obtain the SharePoint AES 256 encryption key from registry

As a matter of playing with the passphrase, or troubleshooting, you can also look at what data is stored in the registry value CredentialKeyDPEnt. The data is actually DPAPI protected with LocalMachine context. In order to decrypt (unprotect) the data, you simple call the System.Security.Cryptography.ProtectedData.Unprotect() method. The method accepts an initialization vector (IV, optionalEntropy) which has been used previously to protect the data with System.Security.Cryptography.ProtectedData.Protect() method.

The initialization vector is used to give the protection some additional entropy and/or provide some opaqueness and separation among applications running on the same machine. The IV is well-known and is not anything secret generally. SharePoint uses its farm GUID for the optionalEntropy parameter. You can obtain the farm GUID with Get-SPFarm cmdlet from its Id member.

My BitColdKit tool contains a simple function BitColdKit-DpapiUnprotect which you can simply use to extract the SharePoint AES 256 bit encryption key. You can download the BitColdKit here. Just start the bitcoldkit.bat or import the BitColdKit.psm1 module and then use the following code snippet. You do not need to run this as a member a local Administrators group, because the DPAPI functions with LocalMachine context work for any user account on the computer.

Add-PsSnapIn Microsoft.SharePoint.PowerShell
$spFarm = Get-SPFarm
$spVer = '{0}.{1}' -f $spFarm.BuildVersion.Major, $spFarm.BuildVersion.Minor
BitColdKit-DpapiUnprotect `
  -whatWithIV "HKLM:\Software\Microsoft\Shared Tools\Web Server Extensions\$spVer\Secure\FarmAdmin\CredentialKeyDPEnt" `
  -userOrMachine machine `
  -iv $spFarm.Id.ToByteArray()

Note, that the DPAPI would not be able to decrypt the CredentialKeyDPEnt on any different operating system from which you export the registry value. DPAPI, when used with LocalMachine context, uses a system-wide master encryption key to protect data on a computer. Moving the protected data to another computer is not supported, because you cannot move or specify the DPAPI machine master key from the source computer to the other computer.

That's all folks for today. The next time we look at how to decrypt the configuration database and obtain the private information from it.

Comments

There are no comments for this post.

Add Comment

Title


You do not need to provide any value this column. It will automatically fill with the name of the article itself.

Author *


Body *


Type number two as digit *


This simple antispam field seems to work well. Just put here the number.

Attachments