Share via

3.1.4.6.1 LsarCreateSecret (Opnum 16)

  • Article

The LsarCreateSecret method is invoked to create a new secret object in the server's database.

 NTSTATUS LsarCreateSecret(
   [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 be created.

DesiredAccess: A bitmask that specifies accesses to be granted to the newly created and opened secret object at this time.

SecretHandle: Used to return a handle to the newly created 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.

0xC000000D

STATUS_INVALID_PARAMETER

One of the supplied parameters is invalid. This can happen, for example, if SecretHandle is NULL or if SecretName is not a valid name for a secret object. Secret naming rules are specified in the processing rules shown below for the SecretName parameter.

0xC0000035

STATUS_OBJECT_NAME_COLLISION

The secret object by the specified name already exists.

0xC0000106

STATUS_NAME_TOO_LONG

The length of specified secret name exceeds the maximum set by the server.

0xC0000008

STATUS_INVALID_HANDLE

PolicyHandle is not a valid handle.

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. The server MUST verify that PolicyHandle grants access as specified in section 3.1.4.2.2 with RequiredAccess set to POLICY_CREATE_SECRET.

SecretName: Name of the secret object to be created. The server MUST verify that the string satisfies the RPC_UNICODE_STRING syntax restrictions specified in section 3.1.4.10, and fail the request with STATUS_INVALID_PARAMETER otherwise. The server MUST also check that the following constraints are satisfied by SecretName, and fail the request with STATUS_INVALID_PARAMETER if the name does not check out:

  • Must not be empty.

  • Must not contain the "\" character.<76><77><78>

DesiredAccess: Contains the access bits that the caller is asking to receive for the handle returned in SecretHandle. DesiredAccess is access-checked according to section 3.1.4.2.1. The method-specific portion of the check is the following.

 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 newly created 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

Both "current time" and "old time" attributes of a secret will be set to the server's current time at the instance of creation. Both "old value" and "current value" will be set to NULL until they are modified by the LsarSetSecret message.

The server MUST check that the secret by the name SecretName does not already exist and fail the request with STATUS_OBJECT_NAME_COLLISION otherwise.<79>