Función AcquireCredentialsHandleA (sspi.h)

La función AcquireCredentialsHandle (CredSSP) adquiere un identificador para las credenciales de preexistentes de una entidad de seguridad de . El InitializeSecurityContext (CredSSP) y las funciones AcceptSecurityContext (CredSSP). Estas pueden ser preexistentes credenciales, 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 Esto no es un "inicio de sesión en la red" y no implica la recopilación de credenciales.

 

Sintaxis

SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandleA(
  [in, optional]  LPSTR          pszPrincipal,
  [in]            LPSTR          pszPackage,
  [in]            unsigned long  fCredentialUse,
  [in, optional]  void           *pvLogonId,
  [in, optional]  void           *pAuthData,
  [in, optional]  SEC_GET_KEY_FN pGetKeyFn,
  [in, optional]  void           *pvGetKeyArgument,
  [out]           PCredHandle    phCredential,
  [out, optional] PTimeStamp     ptsExpiry
);

Parámetros

[in, optional] pszPrincipal

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

Nota Si el proceso que solicita el identificador no tiene acceso a las credenciales, la función devuelve un error. Una cadena null indica que el proceso requiere un identificador para las credenciales del usuario en cuyo contexto de seguridad se está ejecutando.

 

[in] pszPackage

Puntero a una cadena terminada en null que especifica el nombre del paquete de seguridad con el que se usarán estas credenciales. Se trata de un nombre de paquete de seguridad devuelto en el miembro Name de una secPkgInfo estructura devuelta por la función EnumerateSecurityPackages. Una vez establecido un contexto, se puede llamar a queryContextAttributes (CredSSP) con ulAttribute establecido en SECPKG_ATTR_PACKAGE_INFO para devolver información sobre el paquete de seguridad en uso.

[in] fCredentialUse

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

Valor	Significado
SECPKG_CRED_INBOUND 0x1	Valide una credencial de servidor entrante. Las credenciales entrantes se pueden validar mediante una entidad de autenticación cuando se llama a initializeSecurityContext (CredSSP) o acceptSecurityContext (CredSSP). Si dicha entidad 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 0x2	Permitir que una credencial de cliente local prepare un token de salida.

[in, optional] pvLogonId

Puntero a un identificador único localmente único (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.

[in, optional] pAuthData

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

[in, optional] pGetKeyFn

Reservado. Este parámetro no se usa y debe establecerse en NULL.

[in, optional] pvGetKeyArgument

Reservado. Este parámetro debe establecerse en NULL.

[out] phCredential

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

[out, optional] ptsExpiry

Puntero a una estructura TimeStamp que recibe la hora en 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

Si la función se realiza correctamente, devuelve SEC_E_OK.

Si se produce un error en la función, devuelve uno de los siguientes códigos de error.

Código devuelto	Descripción
SEC_E_INSUFFICIENT_MEMORY	No hay memoria suficiente disponible para completar la acción solicitada.
SEC_E_INTERNAL_ERROR	Error que no se ha asignado a un código de error SSPI.
SEC_E_NO_CREDENTIALS	No hay credenciales disponibles en el paquete de seguridad de .
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 reconocen las credenciales proporcionadas al paquete.

Observaciones

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

En general, acquireCredentialsHandle (CredSSP) no proporciona las credenciales de otros usuarios que han iniciado sesión en el mismo equipo. Sin embargo, un autor de llamada con privilegios SE_TCB_NAME puede obtener las credenciales de 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 usan esto 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 desde el grupo.

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

Nota

El encabezado sspi.h define AcquireCredentialsHandle como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows Vista [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2008 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	sspi.h (include Security.h)
biblioteca de	Secur32.lib
DLL de	Secur32.dll

Consulte también

AcceptSecurityContext (CredSSP)

FreeCredentialsHandle

InitializeSecurityContext (CredSSP)

funciones SSPI de