Función LsaCallAuthenticationPackage (ntsecapi.h)

  • Artículo

Una aplicación de inicio de sesión usa la función LsaCallAuthenticationPackage para comunicarse con un paquete de autenticación.

Esta función se usa normalmente para acceder a los servicios proporcionados por el paquete de autenticación.

Sintaxis

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

Parámetros

[in] LsaHandle

Identificador obtenido de una llamada anterior a LsaRegisterLogonProcess o LsaConnectUntrusted.

[in] AuthenticationPackage

Proporciona el identificador del paquete de autenticación. Este valor se obtiene llamando a LsaLookupAuthenticationPackage.

[in] ProtocolSubmitBuffer

Un búfer de mensajes específico del paquete de autenticación pasado al paquete de autenticación.

Para obtener información sobre el formato y el contenido de este búfer, consulte la documentación del paquete de autenticación individual.

[in] SubmitBufferLength

Indica la longitud, en bytes, del búfer ProtocolSubmitBuffer .

[out] ProtocolReturnBuffer

Puntero que recibe la dirección del búfer devuelto por el paquete de autenticación.

Para obtener información sobre el formato y el contenido de este búfer, consulte la documentación del paquete de autenticación individual.

Esta función asigna este búfer. Cuando haya terminado de usar este búfer, libere la memoria llamando a la función LsaFreeReturnBuffer .

[out] ReturnBufferLength

Puntero a un ULONG que recibe la longitud del búfer devuelto, en bytes.

[out] ProtocolStatus

Si la función se ejecuta correctamente, este parámetro recibe un código NTSTATUS que indica el estado de finalización del paquete de autenticación.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es STATUS_SUCCESS. Compruebe el parámetro ProtocolStatus para obtener el estado devuelto por el paquete de autenticación.

Si se produce un error en la función, el valor devuelto es un código NTSTATUS . A continuación se muestran los códigos de error posibles.

Código devuelto Descripción
STATUS_QUOTA_EXCEEDED
 No se pudo completar la llamada porque la cuota de memoria del cliente no es suficiente para asignar el búfer de retorno.
STATUS_NO_SUCH_PACKAGE
 El LSA no reconoce el paquete de autenticación especificado.
STATUS_PKINIT_FAILURE
 El cliente Kerberos recibió un certificado KDC que no es válido. Para el inicio de sesión de dispositivo, se requiere una validación estricta de KDC, por lo que el KDC debe tener certificados que usen la plantilla "Autenticación Kerberos" o equivalente. Además, el certificado KDC podría expirarse, revocarse o el cliente está bajo un ataque activo de envío de solicitudes al servidor incorrecto.
STATUS_PKINIT_CLIENT_FAILURE
 El cliente Kerberos usa un certificado del sistema que no es válido. Para el inicio de sesión del dispositivo, debe haber un nombre DNS. Además, el certificado del sistema podría expirar o se podría seleccionar uno incorrecto.
 

Para obtener más información, vea Valores devueltos de la función de directiva LSA.

La función LsaNtStatusToWinError convierte un código NTSTATUS en un código de error de Windows.

Comentarios

Las aplicaciones de inicio de sesión pueden llamar a LsaCallAuthenticationPackage para comunicarse con un paquete de autenticación. Hay varias razones por las que una aplicación puede hacer esto:

  • Para implementar protocolos de autenticación de varios mensajes, como el protocolo NTLM Challenge-Response.
  • Para pasar información de cambio de estado al paquete de autenticación. Por ejemplo, NTLM podría notificar al paquete de MSV1_0 que ahora se puede acceder a un controlador de dominio inaccesible anteriormente. Después, el paquete de autenticación volvería a iniciar sesión cualquier usuario que haya iniciado sesión en ese controlador de dominio.
Normalmente, esta función se usa para intercambiar información con un paquete de autenticación personalizado. Una aplicación que usa uno de los paquetes de autenticación proporcionados con Windows no necesita esta función, como MSV1_0 o Kerberos.

Debe llamar a LsaCallAuthenticationPackage para limpiar las credenciales del dispositivo PKINIT para LOCAL_SYSTEM y NETWORK_SERVICE. Cuando no hay ninguna credencial de dispositivo PKINIT, una llamada correcta no realiza ninguna operación. Cuando hay una credencial de dispositivo PKINIT, una llamada correcta limpia la credencial del dispositivo PKINIT para que solo permanezca la credencial de contraseña.

Requisitos

Requisito Value
Cliente mínimo compatible Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado ntsecapi.h
Library Secur32.lib
Archivo DLL Secur32.dll

Consulte también

LsaFreeReturnBuffer

LsaLookupAuthenticationPackage

LsaNtStatusToWinError