ホーム › Security.Authentication.Identity › LsaCallAuthenticationPackage

LsaCallAuthenticationPackage

関数

認証パッケージに対しメッセージを送信して処理を要求する。

DLLSECUR32.dll呼出規約winapi対応OSWindows XP 以降

シグネチャ

// SECUR32.dll
#include <windows.h>

NTSTATUS LsaCallAuthenticationPackage(
    HANDLE LsaHandle,
    DWORD AuthenticationPackage,
    void* ProtocolSubmitBuffer,
    DWORD SubmitBufferLength,
    void** ProtocolReturnBuffer,   // optional
    DWORD* ReturnBufferLength,   // optional
    INT* ProtocolStatus   // optional
);

パラメーター

名前	型	方向	説明
LsaHandle	HANDLE	in	以前に LsaRegisterLogonProcess または LsaConnectUntrusted を呼び出して取得したハンドル。
AuthenticationPackage	DWORD	in	認証パッケージの識別子を指定します。この値は LsaLookupAuthenticationPackage を呼び出して取得します。
ProtocolSubmitBuffer	void*	in	認証パッケージに渡される、認証パッケージ固有のメッセージバッファー。このバッファーの形式と内容については、各認証パッケージのドキュメントを参照してください。
SubmitBufferLength	DWORD	in	ProtocolSubmitBuffer バッファーの長さ (バイト単位) を示します。
ProtocolReturnBuffer	void**	outoptional	認証パッケージから返されるバッファーのアドレスを受け取るポインター。このバッファーの形式と内容については、各認証パッケージのドキュメントを参照してください。このバッファーはこの関数によって割り当てられます。このバッファーの使用が終わったら、LsaFreeReturnBuffer 関数を呼び出してメモリを解放してください。
ReturnBufferLength	DWORD*	outoptional	返されたバッファーの長さ (バイト単位) を受け取る ULONG へのポインター。
ProtocolStatus	INT*	outoptional	関数が成功した場合、このパラメーターは認証パッケージの完了状態を示す NTSTATUS コードを受け取ります。

戻り値の型: NTSTATUS

公式ドキュメント

ログオンアプリケーションが認証パッケージと通信するために使用します。

戻り値

関数が成功した場合、戻り値は STATUS_SUCCESS です。認証パッケージから返された状態を取得するには、ProtocolStatus パラメーターを確認してください。

関数が失敗した場合、戻り値は NTSTATUS コードです。考えられるエラーコードを次に示します。

リターンコード	説明
STATUS_QUOTA_EXCEEDED	クライアントのメモリクォータが戻りバッファーを割り当てるのに不足しているため、呼び出しを完了できませんでした。
STATUS_NO_SUCH_PACKAGE	指定された認証パッケージは LSA に認識されていません。
STATUS_PKINIT_FAILURE	Kerberos クライアントが有効でない KDC 証明書を受信しました。デバイスログオンでは厳密な KDC 検証が必要なため、KDC は "Kerberos Authentication" テンプレートまたは同等のテンプレートを使用する証明書を持っている必要があります。また、KDC 証明書の有効期限が切れているか失効している場合や、クライアントが誤ったサーバーに要求を送信させられる能動的な攻撃を受けている可能性もあります。
STATUS_PKINIT_CLIENT_FAILURE	Kerberos クライアントが有効でないシステム証明書を使用しています。デバイスログオンでは DNS 名が必要です。また、システム証明書の有効期限が切れているか、誤った証明書が選択されている可能性もあります。

詳細については、 LSA ポリシー関数の戻り値を参照してください。

LsaNtStatusToWinError 関数は、NTSTATUS コードを Windows エラーコードに変換します。

解説(Remarks)

ログオンアプリケーションは、認証パッケージと通信するために LsaCallAuthenticationPackage を呼び出すことができます。アプリケーションがこれを行う理由はいくつかあります。

NTLM チャレンジ/レスポンスプロトコルなど、複数のメッセージをやり取りする認証プロトコルを実装するため。
状態変更の情報を認証パッケージに渡すため。たとえば、以前は到達できなかったドメインコントローラーに到達できるようになったことを、NTLM が MSV1_0 パッケージに通知する場合があります。認証パッケージはその後、そのドメインコントローラーにログオンしていたすべてのユーザーを再ログオンさせます。

通常、この関数はカスタム認証パッケージと情報を交換するために使用します。MSV1_0 や Kerberos など、Windows に付属する認証パッケージを使用しているアプリケーションでは、この関数は必要ありません。

LOCAL_SYSTEM および NETWORK_SERVICE の PKINIT デバイス資格情報をクリーンアップするには、LsaCallAuthenticationPackage を呼び出す必要があります。PKINIT デバイス資格情報が存在しない場合、呼び出しが成功しても何も行われません。PKINIT デバイス資格情報が存在する場合、呼び出しが成功すると PKINIT デバイス資格情報がクリーンアップされ、パスワード資格情報のみが残ります。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// SECUR32.dll
#include <windows.h>

NTSTATUS LsaCallAuthenticationPackage(
    HANDLE LsaHandle,
    DWORD AuthenticationPackage,
    void* ProtocolSubmitBuffer,
    DWORD SubmitBufferLength,
    void** ProtocolReturnBuffer,   // optional
    DWORD* ReturnBufferLength,   // optional
    INT* ProtocolStatus   // optional
);

[DllImport("SECUR32.dll", ExactSpelling = true)]
static extern int LsaCallAuthenticationPackage(
    IntPtr LsaHandle,   // HANDLE
    uint AuthenticationPackage,   // DWORD
    IntPtr ProtocolSubmitBuffer,   // void*
    uint SubmitBufferLength,   // DWORD
    IntPtr ProtocolReturnBuffer,   // void** optional, out
    IntPtr ReturnBufferLength,   // DWORD* optional, out
    IntPtr ProtocolStatus   // INT* optional, out
);

<DllImport("SECUR32.dll", ExactSpelling:=True)>
Public Shared Function LsaCallAuthenticationPackage(
    LsaHandle As IntPtr,   ' HANDLE
    AuthenticationPackage As UInteger,   ' DWORD
    ProtocolSubmitBuffer As IntPtr,   ' void*
    SubmitBufferLength As UInteger,   ' DWORD
    ProtocolReturnBuffer As IntPtr,   ' void** optional, out
    ReturnBufferLength As IntPtr,   ' DWORD* optional, out
    ProtocolStatus As IntPtr   ' INT* optional, out
) As Integer
End Function

' LsaHandle : HANDLE
' AuthenticationPackage : DWORD
' ProtocolSubmitBuffer : void*
' SubmitBufferLength : DWORD
' ProtocolReturnBuffer : void** optional, out
' ReturnBufferLength : DWORD* optional, out
' ProtocolStatus : INT* optional, out
Declare PtrSafe Function LsaCallAuthenticationPackage Lib "secur32" ( _
    ByVal LsaHandle As LongPtr, _
    ByVal AuthenticationPackage As Long, _
    ByVal ProtocolSubmitBuffer As LongPtr, _
    ByVal SubmitBufferLength As Long, _
    ByVal ProtocolReturnBuffer As LongPtr, _
    ByVal ReturnBufferLength As LongPtr, _
    ByVal ProtocolStatus As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

LsaCallAuthenticationPackage = ctypes.windll.secur32.LsaCallAuthenticationPackage
LsaCallAuthenticationPackage.restype = ctypes.c_int
LsaCallAuthenticationPackage.argtypes = [
    wintypes.HANDLE,  # LsaHandle : HANDLE
    wintypes.DWORD,  # AuthenticationPackage : DWORD
    ctypes.POINTER(None),  # ProtocolSubmitBuffer : void*
    wintypes.DWORD,  # SubmitBufferLength : DWORD
    ctypes.c_void_p,  # ProtocolReturnBuffer : void** optional, out
    ctypes.POINTER(wintypes.DWORD),  # ReturnBufferLength : DWORD* optional, out
    ctypes.POINTER(ctypes.c_int),  # ProtocolStatus : INT* optional, out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('SECUR32.dll')
LsaCallAuthenticationPackage = Fiddle::Function.new(
  lib['LsaCallAuthenticationPackage'],
  [
    Fiddle::TYPE_VOIDP,  # LsaHandle : HANDLE
    -Fiddle::TYPE_INT,  # AuthenticationPackage : DWORD
    Fiddle::TYPE_VOIDP,  # ProtocolSubmitBuffer : void*
    -Fiddle::TYPE_INT,  # SubmitBufferLength : DWORD
    Fiddle::TYPE_VOIDP,  # ProtocolReturnBuffer : void** optional, out
    Fiddle::TYPE_VOIDP,  # ReturnBufferLength : DWORD* optional, out
    Fiddle::TYPE_VOIDP,  # ProtocolStatus : INT* optional, out
  ],
  Fiddle::TYPE_INT)

#[link(name = "secur32")]
extern "system" {
    fn LsaCallAuthenticationPackage(
        LsaHandle: *mut core::ffi::c_void,  // HANDLE
        AuthenticationPackage: u32,  // DWORD
        ProtocolSubmitBuffer: *mut (),  // void*
        SubmitBufferLength: u32,  // DWORD
        ProtocolReturnBuffer: *mut *mut (),  // void** optional, out
        ReturnBufferLength: *mut u32,  // DWORD* optional, out
        ProtocolStatus: *mut i32  // INT* optional, out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("SECUR32.dll")]
public static extern int LsaCallAuthenticationPackage(IntPtr LsaHandle, uint AuthenticationPackage, IntPtr ProtocolSubmitBuffer, uint SubmitBufferLength, IntPtr ProtocolReturnBuffer, IntPtr ReturnBufferLength, IntPtr ProtocolStatus);
"@
$api = Add-Type -MemberDefinition $sig -Name 'SECUR32_LsaCallAuthenticationPackage' -Namespace Win32 -PassThru
# $api::LsaCallAuthenticationPackage(LsaHandle, AuthenticationPackage, ProtocolSubmitBuffer, SubmitBufferLength, ProtocolReturnBuffer, ReturnBufferLength, ProtocolStatus)

#uselib "SECUR32.dll"
#func global LsaCallAuthenticationPackage "LsaCallAuthenticationPackage" sptr, sptr, sptr, sptr, sptr, sptr, sptr
; LsaCallAuthenticationPackage LsaHandle, AuthenticationPackage, ProtocolSubmitBuffer, SubmitBufferLength, ProtocolReturnBuffer, varptr(ReturnBufferLength), varptr(ProtocolStatus)   ; 戻り値は stat
; LsaHandle : HANDLE -> "sptr"
; AuthenticationPackage : DWORD -> "sptr"
; ProtocolSubmitBuffer : void* -> "sptr"
; SubmitBufferLength : DWORD -> "sptr"
; ProtocolReturnBuffer : void** optional, out -> "sptr"
; ReturnBufferLength : DWORD* optional, out -> "sptr"
; ProtocolStatus : INT* optional, out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "SECUR32.dll"
#cfunc global LsaCallAuthenticationPackage "LsaCallAuthenticationPackage" sptr, int, sptr, int, sptr, var, var
; res = LsaCallAuthenticationPackage(LsaHandle, AuthenticationPackage, ProtocolSubmitBuffer, SubmitBufferLength, ProtocolReturnBuffer, ReturnBufferLength, ProtocolStatus)
; LsaHandle : HANDLE -> "sptr"
; AuthenticationPackage : DWORD -> "int"
; ProtocolSubmitBuffer : void* -> "sptr"
; SubmitBufferLength : DWORD -> "int"
; ProtocolReturnBuffer : void** optional, out -> "sptr"
; ReturnBufferLength : DWORD* optional, out -> "var"
; ProtocolStatus : INT* optional, out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "SECUR32.dll"
#cfunc global LsaCallAuthenticationPackage "LsaCallAuthenticationPackage" sptr, int, sptr, int, sptr, sptr, sptr
; res = LsaCallAuthenticationPackage(LsaHandle, AuthenticationPackage, ProtocolSubmitBuffer, SubmitBufferLength, ProtocolReturnBuffer, varptr(ReturnBufferLength), varptr(ProtocolStatus))
; LsaHandle : HANDLE -> "sptr"
; AuthenticationPackage : DWORD -> "int"
; ProtocolSubmitBuffer : void* -> "sptr"
; SubmitBufferLength : DWORD -> "int"
; ProtocolReturnBuffer : void** optional, out -> "sptr"
; ReturnBufferLength : DWORD* optional, out -> "sptr"
; ProtocolStatus : INT* optional, out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。