Función AcquireCredentialsHandle (General)

  • Artículo

La función AcquireCredentialsHandle (General) adquiere un identificador para las credenciales preexistentes de una entidad de seguridad. Las funciones InitializeSecurityContext (General) y AcceptSecurityContext (General) 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:

Esto no es un "inicio de sesión en la red" y no implica la recopilación de credenciales.

 

Para obtener información sobre el uso de esta función con un proveedor de compatibilidad de seguridad específico (SSP), consulte los temas siguientes.

Tema Descripción
AcquireCredentialsHandle (CredSSP)
 Adquiere un identificador para las credenciales preexistentes de una entidad de seguridad que usa el proveedor de compatibilidad de seguridad de credenciales (CredSSP).
AcquireCredentialsHandle (Digest)
 Adquiere un identificador para las credenciales preexistentes de una entidad de seguridad que usa Digest.
AcquireCredentialsHandle (Kerberos)
 Adquiere un identificador para las credenciales preexistentes de una entidad de seguridad que usa Kerberos.
AcquireCredentialsHandle (Negotiate)
 Adquiere un identificador para las credenciales preexistentes de una entidad de seguridad que usa Negotiate.
AcquireCredentialsHandle (NTLM)
 Adquiere un identificador para las credenciales preexistentes de una entidad de seguridad que usa NTLM.
AcquireCredentialsHandle (Schannel)
 Adquiere un identificador para las credenciales preexistentes de una entidad de seguridad que usa Schannel.

 

Sintaxis

SECURITY_STATUS SEC_Entry AcquireCredentialsHandle(
  _In_  SEC_CHAR       *pszPrincipal,
  _In_  SEC_CHAR       *pszPackage,
  _In_  ULONG          fCredentialUse,
  _In_  PLUID          pvLogonID,
  _In_  PVOID          pAuthData,
  _In_  SEC_GET_KEY_FN pGetKeyFn,
  _In_  PVOID          pvGetKeyArgument,
  _Out_ PCredHandle    phCredential,
  _Out_ PTimeStamp     ptsExpiry
);

Parámetros

pszPrincipal [in]

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

Cuando se usa el SSP de resumen, este parámetro es opcional.

Al usar el SSP de Schannel, este parámetro no se usa y debe establecerse en NULL.

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.

 

pszPackage [in]

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 estructura SecPkgInfo devuelta por la función EnumerateSecurityPackages . Una vez establecido un contexto, se puede llamar a QueryContextAttributes (General) con ulAttribute establecido en SECPKG_ATTR_PACKAGE_INFO para devolver información sobre el paquete de seguridad en uso.

Al usar el SSP de resumen, establezca este parámetro en WDIGEST_SP_NAME.

Al usar el SSP de Schannel, establezca este parámetro en UNISP_NAME.

fCredentialUse [in]

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

Valor Significado
SECPKG_CRED_AUTOLOGON_RESTRICTED
0x00000010
 La seguridad no usa credenciales de inicio de sesión predeterminadas ni credenciales del Administrador de credenciales.
Este valor solo es compatible con la delegación restringida negotiate.
Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Este valor no se admite.
SECPKG_CRED_BOTH
 Valide una credencial entrante o use una credencial local para preparar un token saliente. Esta marca habilita ambas marcas. Esta marca no es válida con los SSP digest y Schannel.
SECPKG_CRED_INBOUND
 Valide una credencial de servidor entrante. Las credenciales entrantes se pueden validar mediante una entidad de autenticación cuando se llama a InitializeSecurityContext (General) o AcceptSecurityContext (General). 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 saliente.
SECPKG_CRED_PROCESS_POLICY_ONLY
0x00000020
 La función procesa la directiva del servidor y devuelve SEC_E_NO_CREDENTIALS, lo que indica que la aplicación debe solicitar credenciales.
Este valor solo es compatible con la delegación restringida negotiate.
Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Este valor no se admite.

 

pvLogonID [in]

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.

Al usar el SSP de Schannel, este parámetro no se usa y debe establecerse en NULL.

pAuthData [in]

Puntero a datos específicos del paquete. Este parámetro puede ser NULL, lo que indica que se deben usar las credenciales predeterminadas para ese paquete de seguridad . Para usar las credenciales proporcionadas, pase una estructura de SEC_WINNT_AUTH_IDENTITY que incluya esas credenciales en este parámetro. El tiempo de ejecución de RPC pasa lo que se proporcionó en RpcBindingSetAuthInfo.

Cuando se usa el SSP de resumen, este parámetro es un puntero a una estructura de SEC_WINNT_AUTH_IDENTITY que contiene información de autenticación que se va a usar para buscar las credenciales.

Al usar el SSP de Schannel, especifique una estructura de SCHANNEL_CRED que indique el protocolo que se va a usar y la configuración de varias características de canal personalizables.

Al usar los paquetes NTLM o Negotiate, las longitudes de caracteres máximas para el nombre de usuario, la contraseña y el dominio son 256, 256 y 15, respectivamente.

pGetKeyFn [in]

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

pvGetKeyArgument [in]

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

phCredential [out]

Puntero a una estructura CredHandle para recibir el identificador de credencial.

ptsExpiry [out]

Puntero a una estructura TimeStamp que recibe la hora en la que expiran las credenciales devueltas. El valor devuelto en esta estructura TimeStamp depende de la delegación restringida. El paquete de seguridad debe devolver este valor en la hora local.

Este parámetro se establece en un tiempo máximo constante. No hay tiempo de expiración para las credenciales o el contexto de seguridadde digest o cuando se usa el SSP de resumen.

Cuando se usa el SSP de Schannel, este parámetro es opcional. Cuando la credencial que se va a usar para la autenticación es un certificado, este parámetro recibe la hora de expiración de ese certificado. Si no se proporcionó ningún certificado, se devuelve un valor de tiempo máximo.

Valor devuelto

Si la función se ejecuta correctamente, la función 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 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 la delegación restringida.
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 AcquireCredentialsHandle (General) devuelve un identificador a las credenciales de una entidad de seguridad, como un usuario o cliente, tal como lo usa una delegación restringida específica. Puede ser el identificador de las credenciales preexistentes, o bien la función puede crear un nuevo conjunto de credenciales y devolverlo. Este identificador se puede usar en llamadas posteriores a las funciones AcceptSecurityContext (General) e InitializeSecurityContext (General).

En general, AcquireCredentialsHandle (General) no permite que un proceso obtenga un identificador para las credenciales de otros usuarios que han iniciado sesión en el mismo equipo. Sin embargo, un llamador con privilegios SE_TCB_NAME tiene la opción de especificar el identificador de inicio de sesión (LUID) de cualquier token de sesión de inicio de sesión existente para obtener un identificador para las credenciales 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 puede 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, deben tenerse 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 .

Requisitos

Requisito Value
Cliente mínimo compatible
 Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible
 Windows Server 2003 [solo aplicaciones de escritorio]
Encabezado
Sspi.h (incluya Security.h)
Biblioteca
Secur32.lib
Archivo DLL
Secur32.dll
Nombres Unicode y ANSI
 AcquireCredentialsHandleW (Unicode) y AcquireCredentialsHandleA (ANSI)

Consulte también

Funciones SSPI

AcceptSecurityContext (General)

InitializeSecurityContext (General)

FreeCredentialsHandle