3.1.4.6.2 LsarOpenSecret (Opnum 28)

  • Article

The LsarOpenSecret method is invoked to obtain a handle to an existing secret object. 

 NTSTATUS LsarOpenSecret(
   [in] LSAPR_HANDLE PolicyHandle,
   [in] PRPC_UNICODE_STRING SecretName,
   [in] ACCESS_MASK DesiredAccess,
   [out] LSAPR_HANDLE* SecretHandle
 );

PolicyHandle: An RPC context handle obtained from either LsarOpenPolicy or LsarOpenPolicy2.

SecretName: The name of the secret object to open.

DesiredAccess: The requested type of access.

SecretHandle: Used to return the handle to the opened secret object.

Return Values: The following is a summary of the return values that an implementation MUST return, as specified by the message processing that follows.

Return value/code

Description

0x00000000

STATUS_SUCCESS

The request was successfully completed.

0xC0000022

STATUS_ACCESS_DENIED

The caller does not have the permissions to perform this operation.

0xC0000034

STATUS_OBJECT_NAME_NOT_FOUND

The secret with the specified name was not found.

0xC0000008

STATUS_INVALID_HANDLE

PolicyHandle is not a valid handle.

0xC000000D

STATUS_INVALID_PARAMETER

Some of the parameters supplied were invalid.

Processing:

This message takes four arguments:

PolicyHandle: An open handle to the policy object. If the handle is not a valid context handle to the policy object or PolicyHandle.HandleType does not equal "Policy", the server MUST return STATUS_INVALID_HANDLE. PolicyHandle.GrantedAccess MUST NOT be considered for this call because the access check MUST happen on the secret object.

SecretName: The name of the secret to be opened. The server MUST verify that the name syntax restrictions on secrets specified in section 3.1.4.6.1 are satisfied, and fail the request with STATUS_INVALID_PARAMETER otherwise. The server MUST verify that the secret object with this name exists in its policy database and fail the request with STATUS_OBJECT_NAME_NOT_FOUND otherwise.<80>

DesiredAccess: A bitmask specifying the type of access that the caller attempts to obtain from the secret object, which is access-checked according to section 3.1.4.2.1. The method-specific portion of the check is as follows:

 IF (IsRequestorAnonymous() and LsaRestrictAnonymous is set to TRUE) THEN
     Return STATUS_OBJECT_NAME_NOT_FOUND
 END IF

The valid secret-rights bits are specified in section 2.2.1.1.4 and the security descriptor is specified in section 3.1.1.4. The IsRequestorAnonymous procedure is specified in section 3.1.4.2.3.

SecretHandle: If the request is successful, this parameter is used to return a handle (section 3.1.1.7) to the opened secret object with its fields initialized as follows:

  • LsaContextHandle.HandleType = "Secret"

  • LsaContextHandle.Object = the secret object

  • LsaContextHandle.GrantedAccess = as specified in section 3.1.4.2.1