AccessCheck 関数 (securitybaseapi.h)

[アーティクル]
08/25/2023

AccessCheck 関数は、セキュリティ記述子が、アクセストークンによって識別されるクライアントに対して、指定されたアクセス権のセットを付与するかどうかを決定します。通常、サーバーアプリケーションはこの関数を使用して、プライベートオブジェクトへのアクセスをチェックします。

構文

BOOL AccessCheck(
  [in]            PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]            HANDLE               ClientToken,
  [in]            DWORD                DesiredAccess,
  [in]            PGENERIC_MAPPING     GenericMapping,
  [out, optional] PPRIVILEGE_SET       PrivilegeSet,
  [in, out]       LPDWORD              PrivilegeSetLength,
  [out]           LPDWORD              GrantedAccess,
  [out]           LPBOOL               AccessStatus
);

パラメーター

[in] pSecurityDescriptor

アクセスがチェックされる SECURITY_DESCRIPTOR 構造体へのポインター。

[in] ClientToken

アクセスを取得しようとしているクライアントを表す偽装トークンへのハンドル。ハンドルには、トークンへのTOKEN_QUERYアクセス権が必要です。それ以外の場合、関数は ERROR_ACCESS_DENIED で失敗します。

[in] DesiredAccess

チェックへのアクセス権を指定するアクセスマスク。このマスクは、汎用アクセス権を含まない MapGenericMask 関数によってマップされている必要があります。

このパラメーターがMAXIMUM_ALLOWEDの場合、この関数は、セキュリティ記述子がクライアントに許可する最大アクセス権を示す GrantedAccess アクセスマスクを設定します。

[in] GenericMapping

アクセスがチェックされているオブジェクトに関連付けられている GENERIC_MAPPING 構造体へのポインター。

[out, optional] PrivilegeSet

アクセス検証の実行に使用される特権を受け取るPRIVILEGE_SET構造体へのポインター。特権が使用されなかった場合、この関数は PrivilegeCount メンバーを 0 に設定します。

[in, out] PrivilegeSetLength

PrivilegeSet パラメーターが指すバッファーのサイズをバイト単位で指定します。

[out] GrantedAccess

付与されたアクセス権を受け取るアクセスマスクへのポインター。 AccessStatus が FALSE に設定されている場合、関数はアクセスマスクを 0 に設定します。関数が失敗した場合、アクセスマスクは設定されません。

[out] AccessStatus

アクセスチェックの結果を受け取る変数へのポインター。セキュリティ記述子で、アクセストークンによって識別されたクライアントに対する要求されたアクセス権が許可されている場合、 AccessStatus は TRUE に設定されます。それ以外の場合、 AccessStatus は FALSE に設定され、 GetLastError を呼び出して拡張エラー情報を取得できます。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

詳細については、「 AccessCheck のしくみの概要」を参照してください。

AccessCheck 関数は、指定したセキュリティ記述子と指定したアクセストークンを比較し、AccessStatus パラメーターでアクセスが許可されるか拒否されるかを示します。アクセスが許可されている場合、要求されたアクセスマスクはオブジェクトに付与されたアクセスマスクになります。

セキュリティ記述子の DACL が NULL の場合、 AccessStatus パラメーターは TRUE を返します。これは、クライアントが要求されたアクセス権を持っていることを示します。

セキュリティ記述子に所有者 SID とグループ SID が含まれていない場合、 AccessCheck 関数は ERROR_INVALID_SECURITY_DESCR で失敗します。

AccessCheck 関数は監査を生成しません。アプリケーションでアクセスチェックの監査が必要な場合は、AccessCheck ではなく AccessCheckAndAuditAlarm、AccessCheckByTypeAndAuditAlarm、AccessCheckByTypeResultListAndAuditAlarm、AccessCheckByTypeResultListAndAuditAlarmByHandle などの関数を使用します。

例

この関数を使用する例については、「 ACL を使用したクライアントアクセスの検証」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows XP (デスクトップアプリのみ)
サポートされている最小のサーバー	Windows Server 2003 (デスクトップアプリのみ)
対象プラットフォーム	Windows
ヘッダー	securitybaseapi.h (Windows.h を含む)
Library	Advapi32.lib
[DLL]	Advapi32.dll