Copyright: Local Security Authority Protected Subsystem


Local Security Authority Protected Subsystem (LSA)

Microsoft® Win32®™

Software Development Kit

Introduction

Local Security Policy

Name-To-SID Translation Services

Posix ID Mapping

The LSA Subsystem Objects and APIs

Classification of LSA APIs

Standard Values Returned By APIs

Common Data Types

Miscellaneous APIs

The Policy Object Type

The Account Object Type

The Private Data Object Type

© Copyright Microsoft Corporation, 1992-1995. All Rights Reserved.


Introduction

This document describes the Local Security Authority subsystem for Windows NT™.

The Local Security Authority (referred to as LSA) is a protected subsystem used to maintain information about all aspects of local security on a system; collectively known as the Local Security Policy of the system.

In addition to housing policy information, the LSA provides various services for translation between names and identifiers. These services include name-to-SID, SID-to-name, privilege programmable name to LUID, privilege LUID to programmable name and privilege programmable name to displayable name.

Microsoft, MS, MS-DOS, Win32, and Windows are registered trademarks and Windows NT is a trademark of Microsoft Corporation in the U.S.A. and other countries.


Local Security Policy

The Local Security Policy of a system is a set of information that:

•	Identifies the domains trusted to authenticate logon attempts.

•	Identifies who may access the system and how they may access the system (interactively, network, as a service).

•	Identifies who is assigned privileges.

•	Identifies what security auditing is to be performed.

•	IEstablishes default memory quotas. This controls how much paged and non-paged pool an individual may use.


LSA Object Types

The LSA information is housed in a number of objects. The types of objects exported by the LSA are:

•	Policy Object

•	TrustedDomain Object

•	Account Object

These object types are described in the following subsections.

Policy Object

This object type is used to control access to the LSA server and also serves to house information that pertains to the entire system, or establishes defaults for the system.

The information housed in this object type includes:

•	System default memory quota. Unless otherwise specified, each user logging on to the system will be assigned this memory quota. Special memory quota values may be assigned to individuals or members of aliases or groups through the Account object type.

•	System-wide security auditing requirements.

•	The name and SID of the Account Domain of this system.

•	Information about the Primary Domain of this system. This information includes the name and SID of the primary domain, an account name within the primary domain to be used for authentication requests and name/ID lookup operations, and the names of domain controllers within the domain. These names may be out of date and should be taken only as a hint. The order of this list is assumed to be significant and will be maintained. This allows, for example, the first name in the list to represent the last-known primary domain controller.

•	An indication of whether the LSA server holds the master copy of the policy information, or a replica. Only part of the policy information is replicated. The remainder is established on a per-system basis.

•	If the LSA server holds replica information, then this object also contains the name of the master server node and an account name to use to access the master for replication.

Exactly one object of type Policy exists. Objects of this type cannot be created or destroyed.

TrustedDomain Object

This object type is used to signify a trust relationship with a domain. This object is used on the trustor's system to identify an account within the trusted domain that may be used to submit authentication requests and to perform other operations, such as name/ID lookup operations.

The information housed in this object type includes:

•	The SID of the trusted domain. This information is not modifiable and must be unique among all TrustedDomain objects.

•	The name of the trusted domain. This information is not modifiable and must be unique among all TrustedDomain objects.

•	The name of the account in the trusted domain used to submit authentication requests and to perform name/SID translations. This name is not modifiable.

•	The password used to submit authentication requests and to perform name / SID translations.

There may be zero or more instances of this object type.

Account Object

This object type is used to assign privileges, system-access capability, and special quotas to individual users, or to members of aliases or groups.

The information housed in this object type includes:

•	The SID of a user account, group account, or alias account.

•	A list of user rights to be assigned to the user or group-alias member. If a user is assigned rights by several Account objects, then an amalgamation of all assigned privileges is produced.

Private Data Object

A limited number of Private Data (or secret) objects are available on each system for the purpose of storing information in a protected (encrypted) fashion. This may be useful for storing server account passwords, for example.

Private data objects are provided primarily to support storage of server account passwords. For example, a database server might need to run in a specific account. The account's password will be needed at server activation time to log the server on. It is expected that two servers of the same type but running on different systems will be run in independent accounts.

Note  Secrets stored using this function are all encrypted using a generated system-specific key. Because the first NT release does not include secure-boot and, thus, has no way to securely store and later retrieve a cryptographic key, the secrets can not truly be considered secure against sophisticated attacks.


Built-in, Account, Primary, And Trusted Domains

The following terms are used to describe domains:

Built-In Domain

The SAM server on each Windows NT and LAN Manager NT system serves exactly one domain called the built-in domain. The name of this domain is BUILTIN.

This domain contains only well-known accounts (user, group and aliases). To date, this domain contains only Alias objects. This may change in the future. No user created accounts are expected in this domain.

The accounts defined in a built-in domain may only be used within the system upon which it resides (or cluster of systems, in the LAN Manager NT case).

Account Domain

The SAM server on each Windows NT and LAN Manager NT system serves exactly one domain called the Account Domain. The name of this domain is assigned at system installation time as follows:

For Windows NT systems, the Account domain name is initially set to match the computer name (excluding the leading backslashes). If the computer name is subsequently changed by an administrator, the Account domain name remains unchanged until the next time the system is restarted, at which time, the LSA automatically updates the name to match the new computer name.

For LanMan-NT systems (Domain Controllers), the Account domain name is set to match the name of the controlled domain, which is also the Primary Domain for these systems.

This domain contains Microsoft-defined and user-defined user, group, and alias accounts. The workstation administrator's account is in this domain. On a Windows NT system that has no primary domain, this domain is used to house all accounts of users who may access the system.

On a Windows NT system that has a primary domain, this domain will typically only house accounts for unusual guests (such as children or friends that don't otherwise have access to the network); normal accounts are expected to be defined within Account Domains of LAN Manager NT systems.

On a LAN Manager NT system, the Account Domain contains normal user and group accounts that may be used in any system that in some way trusts this domain for authentication.

Primary Domain

Is a term used to signify the set of LAN Manager NT systems that a Windows NT system places all responsibility for establishing further trust relationships and performing authentication (or passing the authentication request on to an appropriate trusted domain). When logon occurs, the Built-in and Account domains are checked for authentication. If the account being logged onto is not in either of these domains, the logon request is handed off the to system's primary domain.

Trusted Domain

Is a term used to signify a special form of trust that one set of LAN Manager NT systems (called a cluster) may place in another cluster of LAN Manager NT systems. Saying that a domain is trusted means that the cluster is trusted to authenticate logon attempts against its Account Domain for the trusting domain. (Note that it would appear that Trusted Cluster would be more appropriate for this behavior. However, in a future distributed security environment, the trust will really be in the form of trusting a certifying authority. In this case logon attempts will not need to be passed through to a remote cluster, but will be verified against a set of cryptographically signed certificates.)

In addition to the use of the term Trusted Domain, there is also an object type of the LSA called a TrustedDomain object type. This object type is used house information regarding the trust relationship, including name/SID of the trusted domain, the account in the domain to use for authentication and name/ID translation requests, and the names of domain controllers in that domain.

On a Windows NT system, a TrustedDomain object is used to identify this same information for a primary domain rather than trusted domains.

The AccountDomain and PrimaryDomain fields of the Policy object and the TrustedDomain object type are used for different purposes depending upon system type (Windows NT or LAN Manager NT) and on what trust relationships exist. The following configurations produce interesting combinations of these field/object values:

•	A Windows NT system that is not part of a primary domain.

In this case, the AccountDomain field of the Policy object contains the name/SID of the system's local account domain. The name, in this case, is the same as the computer name (as at the time of system startup). The Policy object's PrimaryDomain field contains the name of the workgroup this machine is a member of. Any TrustedDomain objects that might happen to exist are ignored - although there can not be a TrustedDomain object with the same name as the workgroup or it will appear as though it is the machine's primary domain (see following).

•	A Windows NT system that is part of a primary domain.

As with the previous case, the AccountDomain field identifies the name/SID of the local AccountDomain. However, now the PrimaryDomain field also contains the name/SID of the primary domain for the system. Additionally, there is expected to be a TrustedDomain object with the name/SID identified in the PrimaryDomain field. This TrustedDomain object contains the account name and server name information necessary to establish a secure channel to a domain controller in the primary domain. Any other TrustedDomain objects that might happen to exist are ignored.

•	A LAN Manager NT system.

As with Windows NT systems, the AccountDomain field continues to identify the local account domain for the system. In this case, however, the account name is user assigned rather than a well-known name.

Since the Primary Domain of a LAN Manager NT system is the same as the Account Domain, the PrimaryDomain field must contain the same value as the AccountDomain field. Furthermore, all TrustedDomain objects are expected to be valid and represent trust relationships with other domains. If the system does not trust any other domains, then there should be zero TrustedDomain objects.


Name-To-SID Translation Services

The LSA provides services for translating user, group, and alias names into their corresponding SID values, and vice versa. Using the trust relationships established for authentication purposes, these services can translate a number of names from any of the domains trusted for authenticating users for access to the LSA's system.

These translation services are primarily provided for use by Permissions editors for the display of ACL information. Note that a permission editor should always remote the translation service to the LSA on the system at which the target resource resides. This ensures that the proper set of trusted domains is referenced during the translation.


Posix ID Mapping

The Posix subsystem must be able to translate any SID it encounters to a 32-bit value, called a Posix ID. Furthermore, it must be able to categorize the ID as either a user ID or a group ID. To understand how this mapping is accomplished, lets first look at the SIDs that must be mapped.

SIDs have two components: the SID of the domain, and the relative ID of the account in the domain. For example, for the SID S-1-518364-21-43-8, the last "8" is the account's relative ID (or RID) and S-1-518364-21-43 is the SID of the domain.

Different domains known by any particular system are defined through TrustedDomain objects. Part of the information stored in a TrustedDomain object is a Posix ID offset to be used for SIDs within that domain. For example, if the TrustedDomain:

Name:	NtPgm

Sid:	S-1-518364-21-43

Posix Offset:	0x130000

were defined, then Posix IDs for accounts in this domain would be generated by adding 130000 (hex) to the relative ID of the account. So, the Posix ID corresponding to the SID S-1-518364-21-43-8 would be 130008 (hex).

Not all Posix ID translations make use of a TrustedDomain object. The following table shows SIDs that are mapped using well-known offset values:

Source	Posix ID Offset
SIDs from the Built-in Domain	20000 (Hex)
SIDs from the Account Domain	30000 (Hex)
SIDs from the Primary Domain (on Workstations only)	40000 (Hex)
There are also a number of well-known SIDs that don't belong to any domain. These SIDs are mapped using the following well-known offset values:

SID Prefix	Posix ID Offset
	1000 (Hex)
	1100 (Hex)
	1200 (Hex)
	1300 (Hex)
	1400 (Hex)
	1500 (Hex)
	2000 (Hex)
And, finally, one other set of SIDs requires special processing. These are the logon SIDs. These values are assigned by the Windows logon process for each logon session and have the form S-1-5-5-X-Y, where X and Y are treated as a single LARGE_INTEGER that is incremented for each logon session. These SIDs are mapped to the constant Posix ID FFF (Hex). To map the Posix ID FFF(Hex), you may translate whatever logon ID best suits the situation, or S-1-5-5-0-0 by default. (For example, if a posix user applies protection to an object and specifies FFFx, it is better to substitute that user's logon ID than just blindly assigning S-1-5-5-0-0.)


The LSA Subsystem Objects and APIs


Classification of LSA APIs

The LSA APIs are classified according to the type of object on which they operate or the function they perform, if not related to any type of object.

The following API groups exist:

•	Miscellaneous APIs

•	Policy Object APIs
(including name/SID and privilege name/LUID translation API)

•	TrustedDomain Object APIs

•	Account Object APIs

•	Private Data Object APIs


Standard Values Returned By APIs

The following values may be returned by most API routines in addition to those listed in API descriptions.

Value	Meaning
ERROR_SUCCESS	The API call completed successfully.
STATUS_INSUFFICIENT_RESOURCES	There are not enough system resources (such as memory to allocate buffers) to complete the call.
ERROR_INTERNAL_DB_ERROR	The LSA Database contains an internal inconsistency.
ERROR_GEN_FAILURE	Generic failure, such as RPC connection failure.
ERROR_ACCESS_DENIED	Caller does not have the appropriate access to complete the operation.
ERROR_INVALID_SERVER_STATE	Indicates the LSA server is currently disabled.
STATUS_INVALID_SERVER_ROLE	Indicates the action requested is not consistent with the master/replica role of the LSA database. Typically, this means an attempt was made to modify a replicated field or object at a replica node.
ERROR_INVALID_HANDLE	Indicates an object or RPC handle is not valid in the context used.
ERROR_FILE_NOT_FOUND	An object in the LSA Policy Database was not found. The object may have been specified either by SID or by name, depending on its type.


Common Data Types


The LSA_HANDLE Data Type

This type is opaque to the user. Items of this type are called handles. Before an object can be accessed, the local policy object must be opened by calling the appropriate API, LsaOpenPolicy(). A handle is returned which is specified on subsequent calls to API to access the policy database. A handle has associated with it a list of granted accesses which determine which operations can be performed on the policy database. More than one handle may be obtained to the database. When handles are no longer required, they are closed by calling LsaClose().

typedef ULONG LSA_HANDLE, *PLSA_HANDLE;


The LSA_ENUMERATION_HANDLE Data Type

typedef ULONG LSA_ENUMERATION_HANDLE, *PLSA_ENUMERATION_HANDLE;

This type is used by those LSA APIs that perform enumerations of objects in the Policy Database. These APIs are designed so that multiple calls to them can be made to enumerate all of the objects of a given type in the database. On to the initial API call, the caller passes a pointer to a designated ULONG variable that has been initialized to zero. The API call updates this value. When there are more objects to enumerate, the caller should pass the returned value in on the next call to the enumeration API to obtain an enumeration continuing from where the previous call left off.


The LSA_UNICODE_STRING Data Type

typedef struct _LSA_UNICODE_STRING {
USHORT Length;
USHORT MaximumLength;
PWSTR Buffer;
} LSA_UNICODE_STRING, *PLSA_UNICODE_STRING;

Parameters

Length

Length of string in bytes.

MaximumLength

Total length of string buffer, in bytes. Up to MaximumLength of bytes may be written into the buffer without trampling memory.

Buffer

Pointer to a wide character string.

This datatype is equivalent to NT's UNICODE_STRING structure. When ntdef.h is included LSA_UNICODE_STRING is typedef'd to be a UNICODE_STRING.


The LSA_OBJECT_ATTRIBUTES Data Type

typedef struct _LSA_OBJECT_ATTRIBUTES {
ULONG Length;
HANDLE RootDirectory;
PLSA_UNICODE_STRING ObjectName;
ULONG Attributes;
PVOID SecurityDescriptor;
PVOID SecurityQualityOfService;
} LSA_OBJECT_ATTRIBUTES, *PLSA_OBJECT_ATTRIBUTES;

Parameters

Length

Length of LSA_OBJECT_ATTRIBUTES structure in bytes

RootDirectory

Should be NULL

ObjectName

Should be NULL

Attributes

Should be zero

SecurityDescriptor

Should be NULL

SecurityQualityOfService

Points to a SECURITY_QUALITY_OF_SERVICE structure. The impersonation level should be set to SecurityImpersonation and the context tracking mode should be set to SECURITY_DYNAMIC_TRACKING.

This datatype is equivalent to NT's OBJECT_ATTRIBUTES structure. When ntdef.h is included LSA_OBJECT_ATTRIBUTES is typedef'd to be an OBJECT_ATTRIBUTES.


Miscellaneous APIs


LsaFreeMemory

NTSTATUS
LsaFreeMemory(
IN PVOID Buffer
)

Parameters

Buffer

Pointer to memory buffer that was allocated by an LSA API call.

Returned Value

Value	Meaning
ERROR_GEN_FAILURE	Memory could not be freed because it was not allocated by an LSA API call.
Routine Description

This function frees memory allocated by an LSA API call for an output buffer. All LSA APIs that return variable length output buffers always allocate the buffer on behalf of the client. The client is responsible for freeing this memory by passing the returned buffer pointer to this API when the memory is no longer required.


LsaClose

NTSTATUS
LsaClose(
IN LSA_HANDLE ObjectHandle
)

Parameters

ObjectHandle

A handle to an object in the Policy Database. Following completion of this call, the handle is no longer valid.

Return Values

None specific to this API.

Routine Description

This API closes the handle.


LsaNtStatusToWinError

ULONG
LsaNtStatusToWinError(
IN NTSTATUS Status
)

Parameters

Status

An NTSTATUS code returned from an LSA API call.

Return Values

If the status cannot be mapped, ERROR_MR_MID_NOT_FOUND is returned.

Routine Description

This converts an NTSTATUS code to a Windows error code.


The Policy Object Type

This object is a container object. The following object types may reside within this container:

•	Account objects

•	TrustedDomain object

•	Secret object

There is a single instance of the POLICY object. It can be neither created nor destroyed.


Access Types

This object has the following object-specific access types:

POLICY_VIEW_LOCAL_INFORMATION

This access type is needed to read the target system's miscellaneous security policy information. This includes the default quota, auditing, server state/role information, and trust information. This access type is also needed to enumerate trusted domains, accounts, and privileges.

POLICY_GET_PRIVATE_INFORMATION

This access type is needed to view sensitive information, such as the names of accounts established for trusted domain relationships.

POLICY_TRUST_ADMIN

This access type is needed to change the Account Domain or Primary Domain information. This access type is also needed to create TrustedDomain objects.

POLICY_SET_DEFAULT_QUOTA_LIMITS

Set the default system quotas that are applied to user accounts.

POLICY_CREATE_SECRET

This access type is needed to create a new Secret object.

POLICY_CREATE_ACCOUNT

This access type is needed to create a new Account object.

POLICY_SET_AUDIT_REQUIREMENTS

This access type is needed to update the auditing requirements of the system.

POLICY_AUDIT_LOG_ADMIN

This access type is needed to change the characteristics of the Audit Log such as its maximum size or the retention period for audit records, or to clear the log.

POLICY_VIEW_AUDIT_INFORMATION

This access type is needed to view audit log or audit requirements information.

POLICY_SERVER_ADMIN

This access type is needed to modify the server state or role (master/replica) information. It is also needed to change the replica source and account name information.

POLICY_LOOKUP_NAMES

This access type is needed to translate names to SIDs and vice versa.

POLICY_CREATE_PRIVILEGE

Not yet supported.

Generic Access Masks

The POLICY object publishes the following mappings from generic access types to non-generic access types:

GENERIC_READ	STANDARD_RIGHTS_READ |
POLICY_VIEW_AUDIT_INFORMATION |
POLICY_GET_PRIVATE_INFORMATION

GENERIC_WRITE	STANDARD_RIGHTS_WRITE |
POLICY_TRUST_ADMIN |
POLICY_CREATE_ACCOUNT |
POLICY_CREATE_SECRET |
POLICY_CREATE_PRIVILEGE |
POLICY_SET_DEFAULT_QUOTA_LIMITS |
POLICY_SET_AUDIT_REQUIREMENTS |
POLICY_AUDIT_LOG_ADMIN |
POLICY_CREATE_PRIVILEGE |
POLICY_SERVER_ADMIN

GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE |
POLICY_VIEW_LOCAL_INFORMATION |
POLICY_LOOKUP_NAMES

Standard Access Types

This object does not support the (optional) SYNCHRONIZE standard access type. All required access types are supported. The mask of all supported access types for this object type is:

POLICY_ALL_ACCESS      STANDARD_RIGHTS_REQUIRED |
POLICY_VIEW_LOCAL_INFORMATION |
POLICY_VIEW_AUDIT_INFORMATION |
POLICY_GET_PRIVATE_INFORMATION |
POLICY_TRUST_ADMIN |
POLICY_CREATE_ACCOUNT |
POLICY_CREATE_SECRET |
POLICY_CREATE_PRIVILEGE |
POLICY_SET_DEFAULT_QUOTA_LIMITS |
POLICY_SET_AUDIT_REQUIREMENTS |
POLICY_AUDIT_LOG_ADMIN |
POLICY_CREATE_PRIVILEGE |
POLICY_SERVER_ADMIN
POLICY_LOOKUP_NAMES

Privileges Used or Defined

This object type does not define or use any privileges.


Protection_2
Protection

The POLICY object is protected by default in the following fashion:

•	The alias WORLD has GENERIC_EXECUTE access.

•	The well-known ID System is granted POLICY_ALL_ACCESS.

•	The alias LOCAL_ADMIN has GENERIC_READ, GENERIC_WRITE and GENERIC_EXECUTE access.

•	The group LOCAL_ADMIN is assigned as owner and primary group of this object.

The POLICY object cannot be created or destroyed.


Object-Specific Data Types

The POLICY object has the following type-specific data types.


LSA_TRUST_INFORMATION

The following structure is used to identify a domain.

typedef struct _LSA_TRUST_INFORMATION {
LSA_UNICODE_STRING Name;
PSID Sid;
} LSA_TRUST_INFORMATION, * PLSA_TRUST_INFORMATION;

Parameters

Name

Is the name of the domain.

Sid

Is the SID of the domain.


LSA_REFERENCED_DOMAIN_LIST

This data type is used in name and SID lookup services to describe the domains referenced in the lookup operation.

typedef struct	LSA_REFERENCED_DOMAIN_LIST {
ULONG Entries;
PLSA_TRUST_INFORMATION Domains;
} LSA_REFERENCED_DOMAIN_LIST, *PLSA_REFERENCED_DOMAIN_LIST;

Parameters

Entries

Is a count of the number of domains described in the Domains array.

Domains

Is a pointer to an array of Entries LSA_TRUST_INFORMATION data structures.


LSA_TRANSLATED_SID

This data type is used in name to SID lookup services to describe the domains referenced in the lookup operation.

typedef struct	LSA_TRANSLATED_SID {
SID_NAME_USE Use;
ULONG RelativeId;
LONG DomainIndex;
} LSA_TRANSLATED_SID, *PLSA_TRANSLATED_SID;

Paramters

Use

Identifies the use of the SID. If this value is SidUnknown or SidInvalid, then the remainder of the record is not set and should be ignored. If this value is SidDomain, then the DomainIndex field is valid and identifies the domain, but the RelativeId field is not valid and should be ignored.

RelativeId

Contains the relative ID of the translated SID. The remainder of the SID (the prefix) is obtained using the DomainIndex field.

DomainIndex

Is the index of an entry in a related LSA_REFERENCED_DOMAIN_LIST data structure describing the domain in which the account was found.

If there is no corresponding reference domain for an entry, then this field will contain a negative value.


LSA_TRANSLATED_NAME

This data type is used in SID to name lookup services to describe the domains referenced in the lookup operation.

See the description of the name and SID translation services for more information on name syntax/format.

typedef struct	LSA_TRANSLATED_NAME {
SID_NAME_USE Use;
LSA_UNICODE_STRING Name;
LONG DomainIndex;
} LSA_TRANSLATED_NAME, *PLSA_TRANSLATED_NAME;

Parameters

Use

Identifies the use of the name. If this value is SidUnknown or SidInvalid, then the remainder of the record is not set and should be ignored. If this value is SidDomain, then the DomainIndex field is valid and identifies the domain, but the Name field is not valid and should be ignored. If this value is SidWellKnownGroup then the Name field is valid, but the DomainIndex field is not.

Name

Contains the isolated name of the translated SID.

DomainIndex

Is the index of an entry in a related LSA_REFERENCED_DOMAIN_LIST data structure describing the domain in which the account was found.

If there is no corresponding reference domain for an entry, this field will contain a negative value.


POLICY_SYSTEM_ACCESS_MODE

This data type specifies the ways in which a user or member of an alias or group may be allowed to access the system. An account may be granted zero or more of these types of access to the system.

typedef ULONG POLICY_SYSTEM_ACCESS_MODE *PPOLICY_SYSTEM_ACCESS_MODE;
define POLICY_MODE_INTERACTIVE   (0x00000001L)
define POLICY_MODE_NETWORK       (0x00000002L)
define POLICY_MODE_SERVICE       (0x00000004L)

Parameters

Interactive

The user or alias/group member may interactively logon to the system.

Network

The user or alias/group member may access the system through the network (e.g., through shares).

Service

The user or alias may be activated as a service on the system.


POLICY_LSA_SERVER_ROLE

This data type is used to represent the role of the LSA server (primary or backup).

typedef enum POLICY_LSA_SERVER_ROLE {
PolicyServerRoleBackup = 2,
PolicyServerRolePrimary
} POLICY_LSA_SERVER_ROLE, * PPOLICY_LSA_SERVER_ROLE;


POLICY_AUDIT_EVENT_OPTIONS

typedef ULONG POLICY_AUDIT_EVENT_OPTIONS;

Flags can be set within this data type for a given Audit Event Type as follows:

Flag	Meaning
POLICY_AUDIT_EVENT_UNCHANGED	Leave existing auditing options unchanged for events of this type. This flag is used only for set operations. If this flag is set, then all other flags are ignored.
POLICY_AUDIT_EVENT_NONE	Cancel all auditing options for events of this type. If this flag is set, the success/failure flags are ignored.
POLICY_AUDIT_EVENT_SUCCESS	When auditing is enabled, audit all successful occurrences of events of the given type.
POLICY_AUDIT_EVENT_FAILURE	When auditing is enabled, audit all unsuccessful occurrences of events of the given type.


POLICY_PRIVILEGE_DEFINITION

This data type is used to return information about privileges defined on a system.

typedef struct POLICY_PRIVILEGE_DEFINITION {
LSA_UNICODE_STRING Name;
LUID LocalValue;
} POLICY_PRIVILEGE_DEFINITION, *PPOLICY_PRIVILEGE_DEFINITION;

Parameters

Name

Is the architected name of the privilege. This is the primary key of the privilege and the only value that is transportable between systems.

Luid

Is a LUID value assigned locally for efficient representation of the privilege. This value is meaningful only on the system it was assigned on and is not transportable in any way.


Query/Set Information Classes


POLICY_INFORMATION_CLASS

This data type defines the following information classes that may be queried/set.

typedef enum _POLICY_INFORMATION_CLASS_ {
PolicyAuditLogInformation = 1,
PolicyAuditEventsInformation,
PolicyPrimaryDomainInformation,
PolicyPdAccountInformation,
PolicyAccountDomainInformation,
PolicyLsaServerRoleInformation,
PolicyReplicaSourceInformation,
PolicyDefaultQuotaInformation,
PolicyModificationInformation,
PolicyAuditFullSetInformation,
PolicyAuditFullQueryInformation

} POLICY_INFORMATION_CLASS, *PPOLICY_INFORMATION_CLASS;


POLICY_AUDIT_LOG_INFO

The following data type corresponds to the PolicyAuditLogInformation information class. It is used to represent information relating to the audit log.

This structure may only be used in both query and set operations. However, when used in set operations, some fields are ignored.

typedef struct _POLICY_AUDIT_LOG_INFO {
ULONG AuditLogPercentFull;
ULONG MaximumLogSize;
TIME AuditRetentionPeriod;
BOOLEAN AuditLogFullShutdownInProgress;
TIME TimeToShutdown;
} POLICY_AUDIT_LOG_INFO, *PPOLICY_AUDIT_LOG_INFO;

Parameters

AuditLogPercentFull

Indicates what percentage of the Audit Log is currently being used. This field is ignored for set operations.

MaximumLogSize

Specifies the maximum size of the Audit Log in kilobytes.

AuditRetentionPeriod

Indicates the length of time that Audit Records are to be retained. Audit Records are discardable if their timestamp predates the current time minus the retention period.

AuditLogFullShutdownInProgress

Indicates whether or not a system shutdown is being initiated due to the security Audit Log becoming full. This condition will only occur if the system is configured to shutdown when the log becomes full.

TRUE indicates a shutdown is in progress.
FALSE indicates a shutdown is not in progress.

Once a shutdown has been initiated, this flag will be set to TRUE. If an administrator is able to correct the situation before the shutdown becomes irreversible, then this flag will be reset to FALSE.

This field is ignored for set operations.

TimeToShutdown

If the AuditLogFullShutdownInProcess flag is set, then this field contains the time left before the shutdown becomes irreversible.

This field is ignored for set operations.


POLICY_AUDIT_EVENTS_INFO

The following data type corresponds to the PolicyAuditEventsInformation information class. It is used to represent information relating to the audit requirements.

typedef struct POLICY_AUDIT_EVENTS_INFO {
BOOLEAN AuditingMode;
PPOLICY_AUDIT_EVENT_OPTIONS EventAuditingOptions;
ULONG MaximumAuditEventCount;
} POLICY_AUDIT_EVENTS_INFO, * PPOLICY_AUDIT_EVENTS_INFO;

Parameters

AuditingMode

A Boolean variable specifying the Auditing Mode value. This value is interpreted as follows:

TRUE

Auditing is to be enabled (set operations) or is enabled (query operations). Audit Records will be generated according to the Event Auditing Options in effect (see the EventAuditingOptions field).

FALSE

Auditing is to be disabled (set operations) or is disabled (query operations). No Audit records will be generated. Note that for set operations the Event Auditing Options in effect will still be updated as specified by the EventAuditingOptions field whether Auditing is enabled or disabled.

EventAuditingOptions

Pointer to an array of Auditing Options indexed by Audit Event Type.

MaximumAuditEventCount

Specifies a count of the number of Audit Event Types specified by the EventAuditingOptions parameter. If this count is less than the number of Audit Event Types supported by the system, the Auditing Options for event types with ids higher than (MaximumAuditEventCount + 1) are left unchanged.


POLICY_ACCOUNT_DOMAIN_INFO

The following structure corresponds to the PolicyAccountDomainInformation information class.

typedef struct _POLICY_ACCOUNT_DOMAIN_INFO {
LSA_UNICODE_STRING DomainName;
PSID DomainSid;
} POLICY_ACCOUNT_DOMAIN_INFO, * PPOLICY_ACCOUNT_DOMAIN_INFO;


POLICY_PRIMARY_DOMAIN_INFO

The following structure corresponds to the PolicyPrimaryDomainInformation information class.

typedef struct _POLICY_PRIMARY_DOMAIN_INFO {
LSA_UNICODE_STRING Name;
PSID Sid;
} POLICY_PRIMARY_DOMAIN_INFO, * PPOLICY_PRIMARY_DOMAIN_INFO;

Parameters

Name

Is the name of the domain.

Sid

Is the SID of the domain.


POLICY_PD_ACCOUNT_INFO

This structure is no longer used. Workstations will use the workstation name followed by a $ as the account name.


POLICY_LSA_SERVER_ROLE_INFO

The following structure corresponds to the PolicyLsaServerRoleInformation information class.

typedef struct _POLICY_LSA_SERVER_ROLE_INFO {
POLICY_LSA_SERVER_ROLE LsaServerRole;
} POLICY_LSA_SERVER_ROLE_INFO, * PPOLICY_LSA_SERVER_ROLE_INFO;


POLICY_REPLICA_SOURCE_INFO

The following structure corresponds to the PolicyReplicaSourceInformation information class.

typedef struct _POLICY_REPLICA_SOURCE_INFO {
LSA_UNICODE_STRING ReplicaSource;
LSA_UNICODE_STRING ReplicaAccountName;
} POLICY_REPLICA_SOURCE_INFO, * PPOLICY_REPLICA_SOURCE_INFO;


POLICY_DEFAULT_QUOTA_INFO

The following structure corresponds to the PolicyDefaultQuotaInformation information class.

typedef struct _POLICY_DEFAULT_QUOTA_INFO {
QUOTA_LIMITS QuotaLimits;
} POLICY_DEFAULT_QUOTA_INFO, * PPOLICY_DEFAULT_QUOTA_INFO;


POLICY_MODIFICATION_INFO

The following structure corresponds to the PolicyModificationInformation information class.

typedef struct _POLICY_MODIFICATION_INFO {
LARGE_INTEGER ModifiedId;
LARGE_INTEGER DatabaseCreationTime;
} POLICY_MODIFICATION_INFO, * PPOLICY_MODIFICATION_INFO;

Parameters

ModifiedId

Is a 64-bit unsigned integer that is incremented each time anything in the LSA database is modified. This value is only modified on primary domain controllers.

DatabaseCreationTime

Is the date/time that the LSA database was created. On backup domain controllers, this value is replicated from the primary domain controller.


POLICY_AUDIT_FULL_SET_INFO

The following structure corresponds to the PolicyAuditFullSetInformation information class.

typedef struct _POLICY_AUDIT_FULL_SET_INFO {
BOOLEAN ShutDownOnFull;
} POLICY_AUDIT_FULL_SET_INFO, *PPOLICY_AUDIT_FULL_SET_INFO;

Parameters

ShutDownOnFull

When set to TRUE, this boolean indicates that a 	System Shutdown is to be initiated automatically if the audit log fills up.


POLICY_AUDIT_FULL_QUERY_INFO

The following structure corresponds to the PolicyAuditFullQueryInformation information class.

typedef struct _POLICY_AUDIT_FULL_QUERY_INFO {
BOOLEAN ShutDownOnFull;
BOOLEAN LogIsFull;
} POLICY_AUDIT_FULL_QUERY_INFO, *PPOLICY_AUDIT_FULL_QUERY_INFO;

Paramters

ShutDownOnFull

When set to TRUE, this boolean indicates that a System Shutdown is to be initiated automatically if the audit log fills up.

LogIsFull

When set to TRUE, this boolean indicates that the audit log has filled up.


Object API

This section describes the API that provide the methods for accessing the POLICY object.


LsaEnumerateAccountsWithUserRight

NTSTATUS
LsaEnumerateAccountsWithUserRight(
IN LSA_HANDLE PolicyHandle,
IN OPTIONAL PLSA_UNICODE_STRING UserRight,
OUT PVOID *Buffer,
OUT PULONG CountReturned
)

Parameters

PolicyHandle

Handle from an LsaOpenPolicy() call.

UserRight

Optional contains the name of a user right that the enumerated accounts must have.

Buffer

Receives a pointer to an LSA_ENUMERATION_INFORMATION buffer containing information for one or more Account objects. This information is an array of pointers to SIDs.

When this information is no longer needed, it must be released by passing the returned pointer to LsaFreeMemory().

CountReturned

Number of entries returned.

Return Values

Value	Meaning
ERROR_NO_MORE_ITEMS	No entries were returned because there are no more entries to enumerate.
ERROR_NO_SUCH_PRIVILEGE	The user right specified was not a valid user right.
ERROR_NO_MORE_ITEMS	There were no accounts with the specified right.
Routine Description

This API returns information about Accounts objects. This call requires POLICY_VIEW_LOCAL_INFORMATION and POLICY_LOOKUP_NAMES permission to the Policy Object. If a user right is specified, the caller must have ACCOUNT_VIEW permission on account objects.

The enumeration is complete when the error ERROR_NO_MORE_ITEMS is returned.


LsaEnumerateTrustedDomains

NTSTATUS
LsaEnumerateTrustedDomains(
IN LSA_HANDLE PolicyHandle,
IN OUT PLSA_ENUMERATION_HANDLE EnumerationContext,
OUT PVOID *Buffer,
IN ULONG PreferedMaximumLength,
OUT PULONG CountReturned
)

Parameters

PolicyHandle

Handle from an LsaOpenPolicy() call.

EnumerationContext

API specific handle to allow multiple calls (see Routine Description below).

Buffer

Receives a pointer to a buffer containing information for one or more TrustedDomain objects. This information is an array of structures of type LSA_TRUST_INFORMATION.

When this information is no longer needed, it must be released by passing the returned pointer to LsaFreeMemory().

PreferedMaximumLength

Preferred maximum length of returned data (in 8-bit bytes). This is not a hard upper limit, but serves as a guide. Due to data conversion between systems with different natural data sizes, the actual amount of data returned may be greater than this value.

CountReturned

Number of entries returned.

Return Values

Value	Meaning
ERROR_NO_MORE_ITEMS	No entries were returned because there are no more entries to enumerate. This error is returned if the unsigned value specified for the EnumerationContext is too high.
Routine Description

This API returns information about TrustedDomain objects. This call requires POLICY_VIEW_LOCAL_INFORMATION access permission to the Policy Object. Since there may be more information than can be returned in a single call of the routine, multiple calls can be made to get all of the information. To support this feature, the caller is provided with a handle that can be used across calls to the API. On the initial call, EnumerationContext should point to a variable that has been initialized to zero. On each subsequent call, the value returned by the preceding call should be passed in unchanged. The enumeration is complete when the error ERROR_NO_MORE_ITEMS is returned.


LsaLookupNames

NTSTATUS
LsaLookupNames(
IN LSA_HANDLE PolicyHandle,
IN ULONG Count,
IN PLSA_UNICODE_STRING Names,
OUT PLSA_REFERENCED_DOMAIN_LIST *ReferencedDomains,
OUT PLSA_TRANSLATED_SID *Sids
)

Parameters

PolicyHandle

Handle from an LsaOpenPolicy() call.

Count

Specifies the number of names to be translated.

Names

Pointer to an array of Count Unicode Strings to be looked up and mapped to SIDs. The strings may be names of User, Group, or Alias accounts, or domains.

ReferencedDomains

Receives a pointer to a structure describing the domains used for the translation. The entries in this structure are referenced by the structure returned through the SIDs parameter. Unlike the SIDs parameter, which contains an array entry for each translated name, this structure will only contains one component for each domain utilized in the translation.

When this information is no longer needed, it must be released by passing the returned pointer to LsaFreeMemory().

Sids

Receives a pointer to an array of records describing each translated SID. The n (th)  entry in this array provides a translation for the n (th)  entry in the Names parameter.

When this information is no longer needed, it must be released by passing the returned pointer to LsaFreeMemory().

Return Values

Value	Meaning
ERROR_SOME_NOT_MAPPED	Some of the names could not be mapped. This is an informational level status.
ERROR_NONE_MAPPED	None of the names could be translated. This is an error level return value.
Routine Description

This API attempts to translate names of domains, users, groups, or aliases to SIDs. The caller must have POLICY_LOOKUP_NAMES access to the Policy object.

Names may be either isolated (for example, JohnH) or composite names containing both the domain name and account name. Composite names must include a backslash character separating the domain name from the account name (for example, Acctg\JohnH). An isolated name may be either an account name (user, group, or alias) or a domain name.

Translation of isolated names introduces the possibility of name collisions (since the same name may be used in multiple domains). An isolated name will be translated using the following algorithm:

If the name is a well-known name (such as Local or Interactive), then the corresponding well-known SID is returned.

If the name is the built-in domain's name, then that domain's SID is returned.

If the name is the Account domain's name, then that domain's SID is returned.

If the name is the Primary domain's name, then that domain's SID is returned.

If the name is one of the trusted domain's names, then that domain's SID is returned.

If the name is a user, group, or alias in the Built-in domain, then the SID of that account is returned.

If the name is a user, group, or alias in the Account domain, then the SID of that domain is returned.

If the name is a user, group, or alias in the Primary domain, then the SID of that domain is returned.

Otherwise, the name is not translated.

NOTE  Proxy, Machine, and Trust user accounts are not referenced for name translation. Only normal user accounts are used for ID translation. If translation of other account types is needed, then SAM services should be used directly.


LsaLookupSids

NTSTATUS
LsaLookupSids(
IN LSA_HANDLE PolicyHandle,
IN ULONG Count,
IN PSID *Sids,
OUT PLSA_REFERENCED_DOMAIN_LIST *ReferencedDomains,
OUT PLSA_TRANSLATED_NAME *Names
)

Parameters

PolicyHandle

Handle from an LsaOpenPolicy() call.

Count

Specifies the number of SIDs to be translated.

Sids

Pointer to an array of Count pointers to SIDs to be mapped to names. The SIDs may be well-known SIDs, SIDs of User accounts, Group accounts, Alias accounts, or Domains.

ReferencedDomains

Receives a pointer to a structure describing the domains used for the translation. The entries in this structure are referenced by the structure returned through the Names parameter. Unlike the Names parameter, which contains an array entry for each translated name, this structure will only contains one component for each domain utilized in the translation.

When this information is no longer needed, it must be released by passing the returned pointer to LsaFreeMemory().

Names

Receives a pointer to an array of records describing each translated name. The n (th)  entry in this array provides a translation for the n (th)  entry in the Sids parameter.

All of the returned names will be isolated names or null strings (domain names are returned as null strings). If the caller needs composite names, they can be generated by prepending the isolated name with the domain name and a backslash. For example, if the name Sally is returned, and it is from the domain Manufact, then the composite name would be "Manufact" + "\" + "Sally" or "Manufact\Sally".

When this information is no longer needed, it must be released by passing the returned pointer to LsaFreeMemory().

If a SID is not translatable, the following will occur:

If the SID's domain is known, then a reference domain record will be generated with that domain's name. In this case, the name returned through the Names parameter is a Unicode representation of the relative ID of the account, such as "(314)" or the null string, if the SID is that of the domain. So, you might end up with a resultant name of Manufact\(314) for the example with Sally above, if Sally's relative ID is 314.

If not even the SID's domain could be located, then a full unicode representation of the SID is generated and no domain record is referenced. In this case, the returned string might be something like: "(S-1-672194-21-314)".

When this information is no longer needed, it must be released by passing the returned pointer to LsaFreeMemory().

Routine Description

This API attempts to find names corresponding to SIDs. If a name can not be mapped to a SID, the SID is converted to character form. The caller must have POLICY_LOOKUP_NAMES access to the Policy object.


LsaOpenPolicy

NTSTATUS
LsaOpenPolicy(
IN PLSA_UNICODE_STRING SystemName OPTIONAL,
IN PLSA_OBJECT_ATTRIBUTES ObjectAttributes,
IN ACCESS_MASK DesiredAccess,
OUT PLSA_HANDLE PolicyHandle
)

Parameters

SystemName

Name of the system to be administered. The local system is assumed if NULL is specified.

ObjectAttributes

Pointer to the set of attributes to use for this connection. The security Quality Of Service information is used and normally should provide Security Identification level of impersonation. Some operations, however, require Security Impersonation level. APIs requiring higher than Security Identification level are identified in the API description.

DesiredAccess

Is an access mask indicating accesses being requested. These access types are reconciled with the Discretionary Access Control object of the target system to determine whether the accesses will be granted or denied.

PolicyHandle

Receives a handle to be used in future requests.

Return Values

None specific to this API call.

Routine Description

To administer the Local Security Policy of a local or remote system, this API must be called to establish a session with that system's LSA subsystem. This API connects to the LSA of the target system and opens the POLICY object of that system. A handle to the POLICY object is returned. This handle must be used on all subsequent API calls to administer the Local Security Policy information of the target system.


LsaQueryInformationPolicy

NTSTATUS
LsaQueryInformationPolicy(
IN LSA_HANDLE PolicyHandle,
IN POLICY_INFORMATION_CLASS InformationClass,
OUT PVOID *Buffer
)

Parameters

PolicyHandle

Handle from an LsaOpenPolicy() call.

InformationClass

The information structure information level being requested. The accesses required for each information level are shown below:

Information Level	Required Access Type
PolicyAuditLogInformation
	POLICY_VIEW_AUDIT_INFORMATION
PolicyAuditEventsInformation
	POLICY_VIEW_AUDIT_INFORMATION
PolicyPrimaryDomainInformation
	POLICY_VIEW_LOCAL_INFORMATION
PolicyAccountDomainInformation
	POLICY_VIEW_LOCAL_INFORMATION
PolicyPdAccountInformation
	POLICY_GET_PRIVATE_INFORMATION
PolicyLsaServerRoleInformation
	POLICY_VIEW_LOCAL_INFORMATION
PolicyReplicaSourceInformation
	POLICY_VIEW_LOCAL_INFORMATION
PolicyDefaultQuotaInformation
	POLICY_VIEW_LOCAL_INFORMATION
PolicyAuditFullQueryInformation
	POLICY_VIEW_AUDIT_INFORMATION
Buffer

Receives a pointer to the buffer returned containing the requested information. This buffer is allocated by this service and must be freed when no longer needed by passing the returned value to LsaFreeMemory().

Return Values

None specific to this API.

Routine Description

This API obtains information from the policy object.


LsaSetInformationPolicy

NTSTATUS
LsaSetInformationPolicy(
IN LSA_HANDLE PolicyHandle,
IN POLICY_INFORMATION_CLASS InformationClass,
IN PVOID Buffer
)

Parameters

PolicyHandle

Handle from an LsaOpenPolicy() call.

InformationClass

The information structure information level being set. The accesses required for each information level are shown below:

Information Level	Required Access Type
PolicyAuditLogInformation
	POLICY_AUDIT_LOG_ADMIN
PolicyAuditEventsInformation
	POLICY_SET_AUDIT_REQUIREMENTS
PolicyPrimaryDomainInformation
	POLICY_TRUST_ADMIN
PolicyAccountDomainInformation
	POLICY_TRUST_ADMIN
PolicyLsaServerRoleInformation
	POLICY_SERVER_ADMIN
PolicyReplicaSourceInformation
	POLICY_SERVER_ADMIN
PolicyDefaultQuotaInformation
	POLICY_SET_DEFAULT_QUOTA_LIMITS
PolicyAuditFullSetInformation
	POLICY_AUDIT_LOG_ADMIN
Buffer

Points to the buffer containing the specified information level structure.

Return Values

None specific to this API.

Routine Description

This API modifies information in the policy object.


The Account Object Type

Account objects are used to signify special privileges, quotas, or system access that are to be bestowed upon a user or members of groups/aliases.

Account objects reside within the Policy object. There may be zero or more of these objects.


Access Types

The Account object type has the following specific access types:

ACCOUNT_VIEW

This access type is required to read the account information. This includes the privileges assigned to the account, memory quotas assigned, and any special access types granted.

ACCOUNT_ADJUST_PRIVILEGES

This access type is required to assign privileges to or remove privileges from an account.

ACCOUNT_ADJUST_QUOTAS

This access type is required to change the system quotas assigned to an account.

ACCOUNT_ADJUST_SYSTEM_ACCESS

This access type is required to update the System Access flags for the account.

Generic Access Masks:

The Account object type publishes the following mappings from generic access types to non-generic access types:

GENERIC_READ	STANDARD_RIGHTS_READ |
ACCOUNT_VIEW

GENERIC_WRITE	STANDARD_RIGHTS_WRITE |
ACCOUNT_ADJUST_PRIVILEGES |
ACCOUNT_ADJUST_QUOTAS |
ACCOUNT_ADJUST_SYSTEM_ACCESS

GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE

Standard Access Types:

This object does not support the (optional) SYNCHRONIZE standard access type. All required access types are supported. The mask of all supported access types for this object type is:

ACCOUNT_ALL_ACCESS 	STANDARD_RIGHTS_REQUIRED |
ACCOUNT_VIEW |
ACCOUNT_ADJUST_PRIVILEGES |
ACCOUNT_ADJUST_QUOTAS |
ACCOUNT_ADJUST_SYSTEM_ACCESS

Privileges Used or Defined:

This object type does not define or use any privileges.


Protection

Objects of type Account protected in the following fashion:

•	The group WORLD has GENERIC_EXECUTE

•	The group LOCAL_ADMIN has DELETE, GENERIC_READ, GENERIC_WRITE, GENERIC_EXECUTE and WRITE_DACL access.

•	The group LOCAL_ADMIN is assigned as owner and primary group of Account objects.


Object-Specific Data Types

This object has no object-specific data types.


Query/Set Information Classes

This object does not provide a query/set information capability.


Object API

This section describes the API that provide the methods for accessing the objects of type Account.


LsaEnumerateAccountRights

NTSTATUS
LsaEnumerateAccountRights(
IN LSA_HANDLE PolicyHandle,
IN PSID AccountSid,
OUT PLSA_UNICODE_STRING *UserRights,
OUT PULONG CountOfRights
)

Parameters

PolicyHandle

The handle to the local policy object, returned from a preceding LsaOpenPolicy() call.

AccountSid

The SID of the account of which to enumerate rights.

UserRights

Receives a pointer to an array of LSA_UNICODE_STRING structures containing the name of the rights of the account. When this buffer is no longer needed, the caller should release the memory by passing the returned pointer to LsaFreeMemory().

CountOfRights

Receives the number of rights in the UserRights array.

Return Values

None specific to this API.

Routine Description

This API obtains information that describes the privileges assigned to an Account object. All privileges will be obtained in a single call. This call requires ACCOUNT_VIEW access to the Account object.


LsaAddAccountRights

NTSTATUS
LsaAddAccountRights(
IN LSA_HANDLE PolicyHandle,
IN PSID AccountSid,
IN PLSA_UNICODE_STRING UserRights,
IN ULONG CountOfRights
)

Parameters

PolicyHandle

The handle to the open local policy, returned from a preceding LsaOpenPolicy() call.

AccountSid

The SID of the account to which the rights will be added

UserRights

Contains an array of LSA_UNICODE_STRINGs containing the names of the user rights to be added to the account.

Privileges

Points to a set of privileges (and their attributes) to assign to the account.

Return Values

None specific to this API.

Routine Description

This API adds user rights to an Account object. If any provided right is already assigned to the Account object, the new right is ignored. If the account did not exist, it is created. This call requires ACCOUNT_ADJUST_PRIVILEGES access to the Account object and POLICY_LOOKUP_NAMES and POLICY_CREATE_ACCOUNT access to the local policy object.


LsaRemoveAccountRights

NTSTATUS
LsaRemoveAccountRights(
IN LSA_HANDLE PolicyHandle,
IN PSID AccountSid,
IN BOOLEAN AllRights,
IN OPTIONAL PLSA_UNICODE_STRING UserRights,
IN ULONG CountOfRights
)

Parameters

PolicyHandle

The handle to the open local policy, returned from a preceding LsaOpenPolicy() call.

AccountSid

The SID of the account to which the rights will be added.

AllRights

If TRUE, then all rights to be removed from the account and the account is deleted. In this case, the UserRights parameter is ignored. If FALSE, then the UserRights parameter must be supplied.

UserRights

Contains an array of LSA_UNICODE_STRINGs containing the names of the user rights to be added to the account.

Privileges

Points to a set of privileges (and their attributes) to assign to the account.

Return Values

Value	Meaning
ERROR_INVALID_PARAMETER	Indicates the optional UserRights parameter was specified as NULL and AllRights was set to FALSE.
Routine Description

This API removes user rights from the list of those assigned to an Account object. If all the rights have been removed, then the account is deleted. This call requires ACCOUNT_ADJUST_PRIVILEGES and DELETE access to the Account object and POLICY_LOOKUP_NAMES access to the local policy object. The user rights to be removed can either be enumerated explicitly, or all privileges can be removed.


The TrustedDomain Object Type

For a LAN Manager NT system there may be many instances of this object type. For a Windows NT system there is expected to be either zero or one instance (although having more than one doesn't hurt anything). In a Windows NT system, the trusted domain object, if present, is expected to be identified as the Primary Domain of the machine.

TrustedDomain objects have two fields which must be unique among all TrustedDomain objects: the trusted domain's name and the trusted domain's SID. An attempt to create a new TrustedDomain object with either a name or an SID that is already in use by another TrustedDomain object will be rejected.


Access Types

The access types of this object type are:

TRUSTED_QUERY_DOMAIN_NAME

This access type is needed to query the name on the trusted domain.

TRUSTED_SET_CONTROLLERS

This access type is needed to set the list of controllers of the trusted domain.

TRUSTED_QUERY_POSIX

This access type is needed to retrieve the Posix ID offset of a trusted domain.

TRUSTED_SET_POSIX

This access type is needed to set the Posix ID offset of a trusted domain.

Generic Access Masks

This object type has the following generic access mappings:

GENERIC_READ	STANDARD_RIGHTS_READ |
TRUSTED_QUERY_DOMAIN_NAME

GENERIC_WRITE	STANDARD_RIGHTS_WRITE |
TRUSTED_SET_POSIX

GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE |
TRUSTED_QUERY_POSIX

Standard Access Types

This object does not support the (optional) SYNCHRONIZE standard access type. All required access types are supported. The mask of all supported access types for this object type is:

TRUSTED_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED |
TRUSTED_QUERY_DOMAIN_NAME |
TRUSTED_QUERY_CONTROLLERS |
TRUSTED_SET_CONTROLLERS

Privileges Used or Defined

This object type does not define or use any privileges.


Protection

When a TrustedDomain object is created, it is assigned a standard protection. That protection is:

•	The WORLD alias is granted GENERIC_EXECUTE access.

•	The LOCAL_ADMIN alias is granted DELETE, GENERIC_READ, GENERIC_WRITE and GENERIC_EXECUTE access.

•	The LOCAL_ADMIN alias is assigned as owner and primary group of the object.


Object-Specific Data Types

This object has the following object-specific data types.


Query/Set Information Classes

TRUSTED_INFORMATION_CLASS Type

This data type defines the following information classes that may be queried and/or set.

typedef enum _TRUSTED_INFORMATION_CLASS_ {
TrustedDomainNameInformation = 1,
TrustedControllersInformation,
TrustedPosixOffsetInformation,
TrustedPasswordInformation
} TRUSTED_INFORMATION_CLASS, *PTRUSTED_INFORMATION_CLASS;

TRUSTED_DOMAIN_NAME_INFO

The following data type corresponds to the TrustedDomainNameInformation information class.

This structure may be used in Query operations and for Set operations when the domain does not already exist.

typedef struct TRUSTED_DOMAIN_NAME_INFO {
LSA_UNICODE_STRING Name;
} TRUSTED_DOMAIN_NAME_INFO, *PTRUSTED_DOMAIN_NAME_INFO;

Parameters

Name

Is the name of an account in the domain that should be used for authentication and name/ID lookup requests.


TRUSTED_POSIX_OFFSET_INFO

The following data type corresponds to the TrustedPosixOffsetInformation information class.

This structure may be used in both query and set operations.

typedef struct TRUSTED_POSIX_OFFSET_INFO {
ULONG Offset;
} TRUSTED_POSIX_OFFSET_INFO, *PTRUSTED_POSIX_OFFSET_INFO;

Parameters

Offset

Is an offset to use for the generation of Posix user and group IDs from SIDs. The Posix ID corresponding to any particular SID is generated by adding the RID of that SID to the Offset of the SID's corresponding TrustedDomain object.


TRUSTED_PASSWORD_INFO

The following data type corresponds to the TrustedPasswordInformation information class.

This structure may be used in both query and set operations.

typedef struct TRUSTED_PASSWORD_INFO {	LSA_UNICODE_STRING Password;
LSA_UNICODE_STRING OldPassword;
} TRUSTED_PASSWORD_INFO, *PTRUSTED_PASSWORD_INFO;

Parameters

Password

Is the password to use when creating an authenticated connection to the domain.

OldPassword

Is the old password used when creating an authenticated connection to the domain. On Set operations, if the Buffer pointer of the old password is NULL the old password is set to be the same as the password.


Object API

This section describes the API that provide the methods for accessing this object type.

NTSTATUS
LsaQueryTrustedDomainInfo(
IN LSA_HANDLE PolicyHandle,
IN PSID DomainSid,
IN ULONG InformationLevel,
OUT PVOID *Buffer
)

Parameters

TrustedDomainHandle

Handle from an LsaOpenPolicy() call.

DomainSid

SID of the domain to query.

InformationLevel

The information structure information level being requested. The accesses required for each information level are shown below:

Information Level	Required Access Type
TrustedDomainNameInformation	TRUSTED_QUERY_DOMAIN_NAME
TrustedPosixOffsetInformation	TRUSTED_QUERY_POSIX
TrustedPasswordInformation	TRUSTED_QUERY_DOMAIN_NAME
Buffer

Receives a pointer to the buffer returned containing the requested information. This buffer is allocated by this service and must be freed when no longer needed by passing the returned value to LsaFreeMemory().

Return Values

None specific to this API.

Routine Description

This API obtains information from a TrustedDomain object.


LsaSetTrustedDomainInformation

NTSTATUS
LsaSetTrustedDomainInformation(
IN LSA_HANDLE PolicyHandle,
IN PSID DomainSid,
IN ULONG InformationLevel,
IN PVOID Buffer
)

Parameters

PolicyHandle

Handle from an LsaOpenPolicy() call.

DomainSid

SID of domain on which to set information.

InformationLevel

The information structure information level being set. The accesses required for each information level are shown below:

Information Level	Required Access Type
TrustedDomainNameInformation	POLICY_ADMIN_TRUSTED
TrustedPosixOffsetInformation	TRUSTED_SET_POSIX
TrustedPasswordInformation	TRUSTED_QUERY_DOMAIN_NAME and POLICY_CREATE_SECRET
Buffer

Points to the buffer containing the specified information level structure.

Return Values

None specific to this API.

Routine Description

This API modifies information in the TrustedDomain object. If InformationLevel is TrustedDomainNameInformation and the domain does not exist, it is created. This operation requires POLICY_ADMIN_TRUSTED permission on the local policy object.


LsaDeleteTrustedDomain

NTSTATUS
LsaDeleteTrustedDomain(
IN LSA_HANDLE PolicyHandle,
IN PSID DomainSid
)

Parameters

PolicyHandle

Handle from an LsaOpenPolicy() call.

DomainSid

SID of domain to delete.

Return Values

None specific to this API.

Routine Description

This API deletes a trusted domain. It requires DELETE and TRUSTED_QUERY_DOMAIN_NAME access to the trusted domain.

This API modifies information in the TrustedDomain object.


The Private Data Object Type


Access Types

The access types of this object type are:

SECRET_QUERY_VALUE

This access type is needed to retrieve a secret.

SECRET_SET_VALUE

This access type is needed to modify a secret.

Generic Access Masks:

This object type has the following generic access mappings:

GENERIC_READ	STANDARD_RIGHTS_READ |
SECRET_QUERY_VALUE

GENERIC_WRITE	STANDARD_RIGHTS_WRITE |
SECRET_SET_VALUE

GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE

Standard Access Types:

This object does not support the (optional) SYNCHRONIZE standard access type. All required access types are supported. The mask of all supported access types for this object type is:

SECRET_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED |
SECRET_QUERY_VALUE |
SECRET_SET_VALUE

Privileges Used or Defined:

This object type does not define or use any privileges.


Initial Protection

When a Private Data object is created, it is assigned a standard protection. That protection is:

•	The WORLD alias is granted GENERIC_EXECUTE access.

•	The LOCAL_ADMIN alias is granted DELETE, GENERIC_READ, GENERIC_WRITE and GENERIC_EXECUTE access.

•	The LOCAL_ADMIN alias is assigned as owner and primary group of the object.


Object-Specific Data Types

This object has no object-specific data types.


Object API

This section describes the API that provide the methods for accessing this object type.


LsaStorePrivateData

NTSTATUS
LsaStorePrivateData(
IN LSA_HANDLE PolicyHandle,
IN PLSA_UNICODE_STRING KeyName,
IN PLSA_UNICODE_STRING PrivateData
)

Parameters

PolicyHandle

Handle from an LsaOpenPolicy() call.

KeyName

Name under which the private data is stored.

PrivateData

Private data to store.

Return Values

None specific to this API.

Routine Description

This stores private data in the registry. While the data stored is not absolutely protected, it has an ACL allowing only the creator and administrators to read the data and is encrypted before being stored. The PolicyHandle must be opened with POLICY_CREATE_SECRET permission if this is the first time data is being stored under KeyName. If PrivateData is a NULL pointer, then the private data entry is deleted and attempts to retrieve it will return ERROR_FILE_NOT_FOUND.


LsaRetrievePrivateData

NTSTATUS
LsaRetrievePrivateData(
IN LSA_HANDLE PolicyHandle,
IN PLSA_UNICODE_STRING KeyName,
OUT PLSA_UNICODE_STRING * PrivateData
)

Parameters

PolicyHandle

Handle from an LsaOpenPolicy() call.

KeyName

Name under which private data is stored.

PrivateData

Receives a pointer to an LSA_UNICODE_STRING structure containing the private data. KeyName should be freed with the LsaFreeMemory() API.

Return Values

Value	Meaning
ERROR_FILE_NOT_FOUND	No private data was stored under the name KeyName.
Routine Description

This API retrieves private data that was stored with the LsaStorePrivateData() API. It sets the workstation's password and old password to the value of Password. POLICY_CREATE_SECRET permission to the local policy object is required.