Administer > Global Shell: Windows subauthentication package

Global Shell: Windows subauthentication package

Under Microsoft® Windows, a program (service or application) cannot obtain a handle to a login session for a user account without supplying the password for that user account. Without both the user name and password, a running program cannot impersonate or act as a user other than the user in whose identity the program is currently running.

This restriction also applies to SA Agents. The SA Agent is installed to run in the LocalSystem security context. The LocalSystem logon session is a special, trusted, and privileged security context that is created at boot time on every Windows server that is running Windows Server 2003, 2008, and 2012 operating systems. However, if the SA Agent needs to run a child process in the security context of another user (such as <DOMAIN>\<username>), it requires the password for that user account. The user name, password, and child program name are all passed to the Win32 API LogonUser().

The SA Agent performs actions on a managed server on behalf of the SA Global Shell feature. An SA user can perform registry read operations, file creation, and browsing operations on a managed server by using the Global Shell feature and the SA Agent. If an SA user wants to perform the operation as a LocalSystem user, the SA Agent only needs to create a subprocess running in the same security context of the Agent itself. If an SA user wants to perform a Global Shell operation as a non-LocalSystem user, the Agent cannot use the Win32 API LogonUser() because it requires the user account password. See the SA 10.60 User Guide for more information about Global Shell operations.

Microsoft Windows authentication process

Microsoft Windows authentication is a process that verifies whether a user is authorized to access a system. During this verification process, the user provides a password that is cryptographically hashed. This hashed value is then compared with a stored value.

Windows provides a subsystem that supports different forms of authentication. This subsystem is called the Microsoft® Windows Local Security Authority Subsystem (LSAS) and takes the form of a process running the lSAs.exe application on a Windows server.

The design of LSAS allows Windows to support multiple authentication packages. These authentication packages verify a password, a Kerberos token, a thumbprint, a retina pattern, and so on.

In a standard Windows NT4 installation, LSAS has a single authentication package that is called MSV1_0. MSV1_0 is the authentication package that implements NT4 domain authentication. Any time you log in to a Windows NT4 server, providing a user name, password, and domain name, or any time you mount a share on a Windows NT4 server, you are interacting with the MSV1_0 authentication package. On a Windows 2000 server, the set of standard authentication packages consists of MSV1_0 and Kerberos. Depending on the domain configuration, any login attempt will have the user interacting with one of these authentication packages. MSV1_0 and Kerberos are also available as authentication packages on Windows Server 2003, 2008, and 2012.

Microsoft Windows subauthentication package

All of the main Microsoft Windows authentication packages support delegation of the credential check to code that is known as a subauthentication package. A subauthentication package is a DLL that supplements or replaces part of the authentication and validation criteria used by the main authentication package.

The MSV1_0 authentication package can (on the request of a client) defer the verification of user name and password to a previously registered subauthentication package. By default, MSV1_0 use its own internal user name and password checking software. It is only when a Windows client (such as the SA Agent) requests a specific subauthentication module that MSV1_0 delegates to the identified module.

SA subauthentication package

SA provides an MSV1_0 subauthentication package that is requested by the SA Agent when the Agent is authenticating a user on whose behalf a Global Shell operation (such as a child process) must be run. This subauthentication package is a DLL known as ogshcap.dll (where ogshcap represents the Global Shell Custom Authentication and Subauthentication Package).

The ogshcap.dll file is passed the credentials that are supplied to Windows by the client application. This DLL is used on all supported Windows operating systems (Windows Server 2003, 2008 and 2012) and is used in an identical way on each operating system.

The following figure illustrates the subauthentication process in SA.

In the case of the SA Agent, the Agent passes a NULL password along with the user name when it calls a special Windows API to request subauthentication by the SA subauthentication package (ogshcap.dll). The Windows API then calls the MSV1_0 authentication package which, in turn, passes the credentials, including the NULL password to the requested subauthentication package.

The SA subauthentication package performs checks to verify that the user account is not locked out or disabled, and that the calling client is the SA Agent. The DLL ignores the password field, which is empty (NULL). After its verification steps are passed, the DLL returns a success status to MSV1_0, which creates a login session that is then passed to LSAS. In turn, LSAS passes a handle to this login session to the SA Agent. This handle to a login session is then passed by the SA Agent to a call to the Win32 API CreateProcesSAUser() to run the child process in the identity of the non-LocalSystem user.

After Windows has been requested to perform a single subauthentication operation using the ogshcap.dll file, Windows opens this file and keeps it open until the server next reboots. This means that the ogshcap.dll cannot be deleted before the next reboot, nor can it be overwritten during an Agent installation or upgrade without a reboot.

For all Windows operating systems, the user name of the security principal being authenticated must be a member of the Administrators group on the local server or of the Domain Admins group of the Primary Domain of which the server is a member.

SA Agent installation changes

During an SA Agent installation on all Windows operating systems, a new Windows registry value is created (if it does not already exist) as the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\MSV1_0

The new registry value is of type REG_SZ and contains:

  • Name: Auth155
  • Value: ogshcap

The SA Agent Installer contains the ogshcap.dll file. During an Agent installation, the ogshcap.dll file is copied to the following source location:

%SystemDrive%:\Program Files\Opsware\bin\ogshcap.dll

After this DLL file is created at this location, the Agent Installer tries to copy it to the following destination location:

%SystemRoot%\system32\ogshcap.dll

If no such file currently exists at the destination location, the copy succeeds. If the copy fails because the file is open and is in use, the Agent Installer calculates a cryptographic hash of both source and destination files. If the source and destination files are different by hash, the Agent Installer calls the Win32 API MoveFileEx(), which creates a Windows-internal registry key. This registry key informs Windows that it must replace the destination file with the source file at the next reboot.

If the hash for one or both DLL files cannot be successfully calculated, the Agent Installer assumes that the replacement of the DLL is warranted. For example, if the Microsoft cryptographic modules cannot be loaded by the Agent Installer, the hash cannot be calculated. The Agent Installer then assumes that the DLL must be replaced.

A post-install reboot can be initiated after the Agent installation by specifying the installer option (--reboot) on the Agent Installer command line.

When a post-install reboot is required to get the latest version of the DLL, the reboot performs a move operation in which the DLL in the source location is moved to the destination location. Therefore, the source DLL file overwrites the destination DLL.

If the existing ogshcap.dll on the operating system must be replaced and a reboot is required to accomplish this, the Agent Installer will not (by default) initiate the reboot. A reboot occurs only if the person performing the installation specifies --reboot as a command-line option.

The --reboot option is accepted by the Agent Installer on all operating systems; however, it is performed only on Windows operating systems. For example, if the
--reboot option is specified during an Agent installation on a Linux 7.2 operating system, a reboot will not be performed by the Agent Installer. In comparison, if the
--reboot option is specified during an Agent installation on a Windows 2000 operating system, a reboot will be performed by the Agent Installer.

If the hashes have been calculated and the source and destination files are verified as identical, no attempt to overwrite the opened ogshcap.dll is made.

The Agent always performs the first-time installation of the ogshcap.dll or the analysis of whether an existing DLL should be overwritten with the version of the DLL that is in the Agent Installer payload. In this case, there is no way to prevent installation of this DLL by the Agent Installer.

If the Agent Installer indicates that a reboot is required and the reboot does not occur after the Agent installation, the SA Agent will be using the out-of-date version of the DLL until the reboot occurs. This means that any bug fixes or modified functionality that are in the new DLL will not be used by the SA Agent until the reboot. However, Windows authentication, on behalf of the SA Agent by the old DLL, will still successfully occur, even while the DLL is marked for replacement by the newer DLL.

The following sample Agent Installer log is from an installation of the ogshcap.dll. In this case, the existing DLL on the operating system does not need to be replaced.

[08/Jun/2005 20:59:18] [INFO] Install CAP file if differing checksum between new and existing file.

[08/Jun/2005 20:59:18] [TRACE] NeedToReplaceOGSHCAPDLL()

[08/Jun/2005 20:59:18] [INFO] Testing CAP file existence:

C:\WINDOWS\system32\ogshcap.dll

[08/Jun/2005 20:59:18] [INFO] C:\WINDOWS\system32\ogshcap.dll CAP file exists

[08/Jun/2005 20:59:18] [TRACE] GenerateKeyToFile()

[08/Jun/2005 20:59:18] [TRACE] Successfully called CreateFile(C:\Program

Files\Common Files\Opsware\cogbot\hmac.key)

[08/Jun/2005 20:59:18] [TRACE] Key file already exists

[08/Jun/2005 20:59:18] [TRACE] C:\Program Files\Common

Files\Opsware\cogbot\hmac.key size: 36 bytes

[08/Jun/2005 20:59:18] [TRACE] Successfully called CloseHandle(C:\Program

Files\Common Files\Opsware\cogbot\hmac.key)

[08/Jun/2005 20:59:18] [TRACE] GenerateKeyToFile() = 1

[08/Jun/2005 20:59:18] [INFO] Calculate MAC for File:

C:\WINDOWS\system32\ogshcap.dll

[08/Jun/2005 20:59:18] [TRACE] C:\WINDOWS\system32\ogshcap.dll size: 40960 bytes

[08/Jun/2005 20:59:18] [TRACE] C:\Program Files\Common

Files\Opsware\cogbot\hmac.key size: 36 bytes

[08/Jun/2005 20:59:18] [TRACE] Successfully called CreateFileMapping() for

C:\WINDOWS\system32\ogshcap.dll

[08/Jun/2005 20:59:18] [TRACE] Successfully called CreateFileMapping() for

C:\Program Files\Common Files\Opsware\cogbot\hmac.key

[08/Jun/2005 20:59:18] [TRACE] CalculateMAC()

[08/Jun/2005 20:59:18] [TRACE] PrintHexBytes()

[08/Jun/2005 20:59:18] [TRACE] HMAC for C:\WINDOWS\system32\ogshcap.dll: 0x02

0x95 0x2B 0x03 0x51 0x02 0x9F 0x6D 0x58 0xF6 0xF1 0x5E 0x1C 0xFC 0x2A 0x72 0x5D

0x7E 0x5F 0xDA

[08/Jun/2005 20:59:18] [TRACE] CalculateMACFromFile() = 1

[08/Jun/2005 20:59:18] [INFO] Calculate MAC for File: C:\Program

Files\Opsware\bin\ogshcap.dll

[08/Jun/2005 20:59:18] [TRACE] C:\Program Files\Opsware\agent\bin\ogshcap.dll size:

40960 bytes

[08/Jun/2005 20:59:18] [TRACE] C:\Program Files\Common

Files\Opsware\cogbot\hmac.key size: 36 bytes

[08/Jun/2005 20:59:18] [TRACE] Successfully called CreateFileMapping() for

C:\Program Files\Opsware\agent\bin\ogshcap.dll

[08/Jun/2005 20:59:18] [TRACE] Successfully called CreateFileMapping() for

C:\Program Files\Common Files\Opsware\cogbot\hmac.key

[08/Jun/2005 20:59:18] [TRACE] CalculateMAC()

[08/Jun/2005 20:59:18] [TRACE] PrintHexBytes()

[08/Jun/2005 20:59:18] [TRACE] HMAC for C:\Program

Files\Opsware\agent\bin\ogshcap.dll: 0x02 0x95 0x2B 0x03 0x51 0x02 0x9F 0x6D 0x58

0xF6 0xF1 0x5E 0x1C 0xFC 0x2A 0x72 0x5D 0x7E 0x5F 0xDA

[08/Jun/2005 20:59:18] [TRACE] CalculateMACFromFile() = 1

[08/Jun/2005 20:59:18] [INFO] C:\WINDOWS\system32\ogshcap.dll CAP file does not

need to be replaced

[08/Jun/2005 20:59:18] [TRACE] NeedToReplaceOGSHCAPDLL() = 0

[08/Jun/2005 20:59:18] [TRACE] UpdateCAPRegistrySetting()

[08/Jun/2005 20:59:18] [INFO] Update SubAuthentication Package Registry key

[08/Jun/2005 20:59:18] [TRACE] Successfully opened registry key

SYSTEM\CurrentControlSet\Control\Lsa\MSV1_0.

[08/Jun/2005 20:59:18] [TRACE] Successfully found registry value: 'Auth255' at

this key, retrieved value 'ogshcap' (8) bytes.

[08/Jun/2005 20:59:18] [TRACE] Existing registry value matches expected value:

'ogshcap'

[08/Jun/2005 20:59:18] [TRACE] UpdateCAPRegistrySetting() = 1

[08/Jun/2005 20:59:18] [INFO] UpdateCapRegistrySetting() was successful

[08/Jun/2005 20:59:18] [TRACE] Win32InstallN() = 1

[08/Jun/2005 20:59:18] [INFO] Installation completed successfully.

[08/Jun/2005 20:59:18] [INFO] An Agent install time reboot is NOT needed.

SA Agent uninstallation changes

During an SA Agent uninstallation, the Windows uninstaller tries to remove the following file:

%SystemRoot%\system32\ogshcap.dll

If the removal fails (because the file is open and is in use by Windows), the uninstaller calls MoveFileEx(), instructing Windows to remove the file during the next reboot. The uninstaller will prompt the user whether it should initiate a reboot immediately, if the attempt to remove the file fails.

The uninstaller also removes the special subauthentication registry key value created at Agent install time.

Send Help Center feedback