DuplicateTokenEx 関数 (securitybaseapi.h)
DuplicateTokenEx 関数は、既存のトークンを複製する新しいアクセス トークンを作成します。 この関数は、 プライマリ トークン または 偽装トークンを作成できます。
構文
BOOL DuplicateTokenEx(
[in] HANDLE hExistingToken,
[in] DWORD dwDesiredAccess,
[in, optional] LPSECURITY_ATTRIBUTES lpTokenAttributes,
[in] SECURITY_IMPERSONATION_LEVEL ImpersonationLevel,
[in] TOKEN_TYPE TokenType,
[out] PHANDLE phNewToken
);
パラメーター
[in] hExistingToken
TOKEN_DUPLICATEアクセスで開かれたアクセス トークンへのハンドル。
[in] dwDesiredAccess
新しいトークンに対して要求されるアクセス権を指定します。 DuplicateTokenEx 関数は、要求されたアクセス権を既存のトークンの随意アクセス制御リスト (DACL) と比較して、許可または拒否される権限を決定します。 既存のトークンと同じアクセス権を要求するには、0 を指定します。 呼び出し元に対して有効なすべてのアクセス権を要求するには、MAXIMUM_ALLOWEDを指定します。
アクセス トークンのアクセス権の一覧については、「 Access-Token オブジェクトのアクセス権」を参照してください。
[in, optional] lpTokenAttributes
新しいトークンのセキュリティ記述子を指定し、子プロセスがトークンを継承できるかどうかを判断する、SECURITY_ATTRIBUTES構造体へのポインター。 lpTokenAttributes が NULL の場合、トークンは既定のセキュリティ記述子を取得し、ハンドルを継承できません。 セキュリティ記述子に システム アクセス制御リスト (SACL) が含まれている場合、 トークンは dwDesiredAccess で要求されていない場合でも、アクセス権ACCESS_SYSTEM_SECURITY取得します。
新しいトークンのセキュリティ記述子で所有者を設定するには、呼び出し元のプロセス トークンに SE_RESTORE_NAME 特権が設定されている必要があります。
[in] ImpersonationLevel
新しいトークンの偽装レベルを示す SECURITY_IMPERSONATION_LEVEL 列挙の値を指定します。
[in] TokenType
TOKEN_TYPE列挙体から次のいずれかの値を指定します。
| 値 | 説明 |
|---|---|
|
新しいトークンは、CreateProcessAsUser 関数で使用できるプライマリ トークンです。 |
|
新しいトークンは偽装トークンです。 |
[out] phNewToken
新しいトークンを受け取る HANDLE 変数へのポインター。
新しいトークンの使用が完了したら、 CloseHandle 関数を呼び出してトークン ハンドルを閉じます。
戻り値
関数が成功した場合、関数は 0 以外の値を返します。
関数が失敗すると、0 が返されます。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
DuplicateTokenEx 関数を使用すると、CreateProcessAsUser 関数で使用できるプライマリ トークンを作成できます。 これにより、クライアントを偽装しているサーバー アプリケーションは、クライアントの セキュリティ コンテキスト を持つプロセスを作成できます。 DuplicateToken 関数は、CreateProcessAsUser では無効な偽装トークンのみを作成できることに注意してください。
DuplicateTokenEx を使用してプライマリ トークンを作成する一般的なシナリオを次に示します。 サーバー アプリケーションは、 ImpersonateNamedPipeClient などの偽装関数のいずれかを呼び出してクライアントを偽装するスレッドを作成します。 その後、偽装スレッドは OpenThreadToken 関数を呼び出して、クライアントのセキュリティ コンテキストを持つ 偽装トークン である独自のトークンを取得します。 スレッドは、 DuplicateTokenEx の呼び出しでこの偽装トークンを指定し、TokenPrimary フラグを指定します。 DuplicateTokenEx 関数は、クライアントのセキュリティ コンテキストを持つプライマリ トークンを作成します。
要件
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | securitybaseapi.h (Windows.h を含む) |
| Library | Advapi32.lib |
| [DLL] | Advapi32.dll |