Funzione LsaCallAuthenticationPackage (ntsecapi.h)

  • Articolo

La funzione LsaCallAuthenticationPackage viene usata da un'applicazione di accesso per comunicare con un pacchetto di autenticazione.

Questa funzione viene in genere usata per accedere ai servizi forniti dal pacchetto di autenticazione.

Sintassi

NTSTATUS LsaCallAuthenticationPackage(
  [in]  HANDLE    LsaHandle,
  [in]  ULONG     AuthenticationPackage,
  [in]  PVOID     ProtocolSubmitBuffer,
  [in]  ULONG     SubmitBufferLength,
  [out] PVOID     *ProtocolReturnBuffer,
  [out] PULONG    ReturnBufferLength,
  [out] PNTSTATUS ProtocolStatus
);

Parametri

[in] LsaHandle

Handle ottenuto da una chiamata precedente a LsaRegisterLogonProcess o LsaConnectUntrusted.

[in] AuthenticationPackage

Fornisce l'identificatore del pacchetto di autenticazione. Questo valore viene ottenuto chiamando LsaLookupAuthenticationPackage.

[in] ProtocolSubmitBuffer

Buffer del messaggio specifico del pacchetto di autenticazione passato al pacchetto di autenticazione.

Per informazioni sul formato e sul contenuto di questo buffer, vedere la documentazione per il singolo pacchetto di autenticazione.

[in] SubmitBufferLength

Indica la lunghezza, in byte, del buffer ProtocolSubmitBuffer .

[out] ProtocolReturnBuffer

Puntatore che riceve l'indirizzo del buffer restituito dal pacchetto di autenticazione.

Per informazioni sul formato e sul contenuto di questo buffer, vedere la documentazione per il singolo pacchetto di autenticazione.

Questo buffer viene allocato da questa funzione. Al termine dell'uso di questo buffer, liberare la memoria chiamando la funzione LsaFreeReturnBuffer .

[out] ReturnBufferLength

Puntatore a un ULONG che riceve la lunghezza del buffer restituito, in byte.

[out] ProtocolStatus

Se la funzione ha esito positivo, questo parametro riceve un codice NTSTATUS che indica lo stato di completamento del pacchetto di autenticazione.

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene STATUS_SUCCESS. Controllare il parametro ProtocolStatus per ottenere lo stato restituito dal pacchetto di autenticazione.

Se la funzione ha esito negativo, il valore restituito è un codice NTSTATUS . Di seguito sono riportati i possibili codici di errore.

Codice restituito Descrizione
STATUS_QUOTA_EXCEEDED
 Impossibile completare la chiamata perché la quota di memoria del client non è sufficiente per allocare il buffer restituito.
STATUS_NO_SUCH_PACKAGE
 Il pacchetto di autenticazione specificato non viene riconosciuto dall'LSA.
STATUS_PKINIT_FAILURE
 Il client Kerberos ha ricevuto un certificato KDC non valido. Per l'accesso del dispositivo, è necessaria una convalida KDC rigorosa, quindi il KDC deve disporre di certificati che usano il modello di autenticazione Kerberos o un equivalente. Il certificato KDC potrebbe anche essere scaduto, revocato o il client è sotto attacco attivo dell'invio di richieste al server errato.
STATUS_PKINIT_CLIENT_FAILURE
 Il client Kerberos usa un certificato di sistema non valido. Per l'accesso del dispositivo, deve essere presente un nome DNS. Inoltre, il certificato di sistema potrebbe essere scaduto o è possibile selezionare quello errato.
 

Per altre informazioni, vedere Valori restituiti della funzione criteri LSA.

La funzione LsaNtStatusToWinError converte un codice NTSTATUS in un codice di errore di Windows.

Commenti

Le applicazioni di accesso possono chiamare LsaCallAuthenticationPackage per comunicare con un pacchetto di autenticazione. Esistono diversi motivi per cui un'applicazione può eseguire questa operazione:

  • Per implementare protocolli di autenticazione a più messaggi, ad esempio il protocollo NTLM Challenge-Response.
  • Per passare le informazioni sulla modifica dello stato al pacchetto di autenticazione. Ad esempio, NTLM potrebbe notificare al pacchetto MSV1_0 che un controller di dominio precedentemente non raggiungibile è ora raggiungibile. Il pacchetto di autenticazione eseguirà quindi di nuovo l'accesso a qualsiasi utente connesso a tale controller di dominio.
In genere, questa funzione viene usata per scambiare informazioni con un pacchetto di autenticazione personalizzato. Questa funzione non è necessaria per un'applicazione che usa uno dei pacchetti di autenticazione forniti con Windows, ad esempio MSV1_0 o Kerberos.

È necessario chiamare LsaCallAuthenticationPackage per pulire le credenziali del dispositivo PKINIT per LOCAL_SYSTEM e NETWORK_SERVICE. Quando non è presente alcuna credenziale del dispositivo PKINIT, una chiamata riuscita non esegue alcuna operazione. Quando è presente una credenziale del dispositivo PKINIT, una chiamata riuscita pulisce le credenziali del dispositivo PKINIT in modo che rimangano solo le credenziali della password.

Requisiti

Requisito Valore
Client minimo supportato Windows XP [solo app desktop]
Server minimo supportato Windows Server 2003 [solo app desktop]
Piattaforma di destinazione Windows
Intestazione ntsecapi.h
Libreria Secur32.lib
DLL Secur32.dll

Vedi anche

LsaFreeReturnBuffer

LsaLookupAuthenticationPackage

LsaNtStatusToWinError