Compartir a través de

Función SspiAcquireCredentialsHandleAsyncA (sspi.h)

  • Artículo

La función SspiAcquireCredentialsHandleAsyncA adquiere asincrónicamente un identificador para las credenciales preexistentes de una entidad de seguridad.

Las funciones SspiInitializeSecurityContextAsync y SspiAcceptSecurityContextAsync requieren este identificador. Estas pueden ser credenciales preexistentes, que se establecen a través de un inicio de sesión del sistema que no se describe aquí, o el autor de la llamada puede proporcionar credenciales alternativas.

Nota

Esta función actúa como el homólogo asincrónico de AcquireCredentialsHandle.

Sintaxis

SECURITY_STATUS SspiAcquireCredentialsHandleAsyncA(
  SspiAsyncContext *AsyncContext,
  LPSTR            pszPrincipal,
  LPSTR            pszPackage,
  unsigned long    fCredentialUse,
  void             *pvLogonId,
  void             *pAuthData,
  SEC_GET_KEY_FN   pGetKeyFn,
  void             *pvGetKeyArgument,
  PCredHandle      phCredential,
  PTimeStamp       ptsExpiry
);

Parámetros

AsyncContext

Contexto de llamada asincrónica.

pszPrincipal

Puntero a una cadena terminada en null que especifica el nombre de la entidad de seguridad cuyas credenciales hará referencia el identificador de forma asincrónica.

pszPackage

Puntero a una cadena terminada en null que especifica el nombre del paquete de seguridad con el que se usarán estas credenciales.

Consulte AcquireCredentialsHandleA: pszPackage

fCredentialUse

Marca que indica cómo se usarán estas credenciales. Este parámetro puede ser uno de los valores siguientes:

Valor
Significado
SECPKG_CRED_INBOUND Valide una credencial de servidor entrante. Las credenciales de entrada se pueden validar mediante una entidad de autenticación cuando se llama a SspiInitializeSecurityContextAsync o SspiAcceptSecurityContextAsync . Si dicha autoridad no está disponible, se producirá un error en la función y se devolverá SEC_E_NO_AUTHENTICATING_AUTHORITY. La validación es específica del paquete.
SECPKG_CRED_OUTBOUND Permitir que una credencial de cliente local prepare un token de salida.

pvLogonId

Puntero a un identificador único local (LUID) que identifica al usuario. Este parámetro se proporciona para los procesos del sistema de archivos, como los redireccionadores de red. Este parámetro puede ser NULL.

pAuthData

Puntero a una estructura de CREDSSP_CRED que especifica los datos de autenticación para los paquetes Schannel y Negotiate.

pGetKeyFn

Puntero a la función GetKey().

pvGetKeyArgument

Pase a GetKey().

phCredential

Puntero a la estructura CredHandle que recibirá el identificador de credencial.

ptsExpiry

Opcional Puntero a una estructura TimeStamp que recibe la hora a la que expiran las credenciales devueltas. El valor de estructura recibido depende del paquete de seguridad, que debe especificar el valor en la hora local.

Valor devuelto

Devuelve SEC_E_OK si la solicitud asincrónica para adquirir un identificador de credenciales se puso en cola correctamente para su ejecución. De lo contrario, devuelve el error generado al intentar ponerla en cola. Para recuperar el estado de la operación, use SspiGetAsyncCallStatus.

Si se adquirió el identificador, SspiGetAsyncCallStatus devuelve SEC_E_OK. De lo contrario, puede devolver SEC_I_ASYNC_CALL_PENDING si la llamada sigue en curso o cualquiera de los siguientes códigos de error irrecuperables en la tabla siguiente.

Código devuelto
Descripción
SEC_E_INSUFFICIENT_MEMORY No hay suficiente memoria disponible para completar la acción solicitada.
SEC_E_INTERNAL_ERROR Error que no se asignación a un código de error de SSPI.
SEC_E_NO_CREDENTIALS No hay credenciales disponibles en el paquete de seguridad
SEC_E_NOT_OWNER El autor de la llamada de la función no tiene las credenciales necesarias.
SEC_E_SECPKG_NOT_FOUND El paquete de seguridad solicitado no existe.
SEC_E_UNKNOWN_CREDENTIALS No se han reconocido las credenciales proporcionadas al paquete.

Comentarios

La función SspiAcquireCredentialsHandleAsyncA devuelve un identificador a las credenciales de una entidad de seguridad, como un usuario o cliente, tal como lo usa un paquete de seguridad específico. La función puede devolver el identificador a credenciales preexistentes o credenciales recién creadas y devolverla. Este identificador se puede usar en llamadas posteriores a las funciones SspiAcceptSecurityContextAsync y SspiInitializeSecurityContextAsync .

En general, SspiAcquireCredentialsHandleAsyncA no proporciona las credenciales de otros usuarios que han iniciado sesión en el mismo equipo. Sin embargo, un autor de llamada con SE_TCB_NAME privilegio puede obtener las credenciales de una sesión de inicio de sesión existente especificando el identificador de inicio de sesión (LUID) de esa sesión. Normalmente, los módulos en modo kernel lo usan los módulos que deben actuar en nombre de un usuario que ha iniciado sesión.

Un paquete podría llamar a la función en pGetKeyFn proporcionada por el transporte en tiempo de ejecución rpc. Si el transporte no admite la noción de devolución de llamada para recuperar credenciales, este parámetro debe ser NULL.

En el caso de los autores de llamadas en modo kernel, se deben tener en cuenta las siguientes diferencias:

  • Los dos parámetros de cadena deben ser cadenas Unicode .
  • Los valores de búfer deben asignarse en la memoria virtual del proceso, no del grupo.

Cuando haya terminado de usar las credenciales devueltas, libere la memoria usada por las credenciales llamando a la función SspiFreeCredentialsHandleAsync .

Requisitos

Requisito Value
Cliente mínimo compatible Windows 10, versión 1607 [solo controladores en modo kernel]
Servidor mínimo compatible Windows Server 2016 [solo controladores en modo kernel]
Encabezado sspi.h

Consulte también

AcquireCredentialsHandle

SspiAcceptSecurityContextAsync

SspiFreeCredentialsHandleAsync

SspiInitializeSecurityContextAsync

Funciones SSPI