AcquireCredentialsHandle (Schannel) işlevi

AcquireCredentialsHandle (Schannel) işlevi, bir güvenlik sorumlusunun önceden var olan kimlik bilgilerini almak için bir tanıtıcı alır. Bu tanıtıcı InitializeSecurityContext (Schannel) ve AcceptSecurityContext (Schannel) işlevleri için gereklidir. Bunlar, burada açıklanmayan bir sistem oturumu aracılığıyla oluşturulan önceden var olan kimlik bilgileri olabilir veya çağıran alternatif kimlik bilgileri sağlayabilir.

Uyarı

Bu bir "ağda oturum açma" değildir ve kimlik bilgilerinin toplandığı anlamına gelmez.

Sözdizimi

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

Parametreler

pszPrincipal[in, optional]

Tanıtıcının başvuracağı kimlik bilgilerine sahip sorumlunun adını belirten null olarak sonlandırılan bir dize işaretçisi.

Schannel SSP kullanılırken bu parametre kullanılmaz ve olarak NULLayarlanmalıdır.

Uyarı

Tanıtıcıyı isteyen işlemin kimlik bilgilerine erişimi yoksa işlev bir hata döndürür. Null dize, işlemin güvenlik bağlamı altında yürütülmekte olan kullanıcının kimlik bilgileri için bir tanıtıcı gerektirdiğini gösterir.

pszPackage[in]

Bu kimlik bilgilerinin kullanılacağı güvenlik paketinin adını belirten null olarak sonlandırılan bir dize işaretçisi. Bu, EnumerateSecurityPackages işlevi tarafından döndürülen Bir SecPkgInfo yapısının Name üyesinde döndürülen bir güvenlik paketi adıdır. Bağlam oluşturulduktan sonra QueryContextAttributes (Schannel), kullanımdaki güvenlik paketiyle ilgili bilgileri döndürmek için SECPKG_ATTR_PACKAGE_INFO olarak ayarlanmış ulAttribute ile çağrılabilir.

Schannel SSP'yi kullanırken, bu parametreyi olarak UNISP_NAMEayarlayın.

Uyarı

AcquireCredentialsHandle(Schannel) çağrıldıktan sonra InitializeSecurityContext (Schannel) çağrılırken sorunlarla karşılaşan çekirdek modu arayanları alternatif olarak pszPackageSCHANNEL_NAMEolarak ayarlayabilir.

fCredentialUse[in]

Bu kimlik bilgilerinin nasıl kullanılacağını gösteren bayrak. Bu parametre aşağıdaki değerlerden biri olabilir.

Değer	Anlamı
SECPKG_CRED_INBOUND	Gelen sunucu kimlik bilgilerini doğrulayın. InitializeSecurityContext (Schannel) veya AcceptSecurityContext (Schannel) çağrıldığında gelen kimlik bilgileri kimlik doğrulama yetkilisi kullanılarak doğrulanabilir. Böyle bir yetkili yoksa işlev başarısız olur ve SEC_E_NO_AUTHENTICATING_AUTHORITY döndürür. Doğrulama pakete özgüdür.
SECPKG_CRED_OUTBOUND	Yerel istemci kimlik bilgilerinin giden belirteci hazırlamasına izin verin.

pvLogonID[in, optional]

Kullanıcıyı tanımlayan yerel olarak benzersiz bir tanımlayıcıya (LUID) yönelik bir işaretçi. Bu parametre, ağ yeniden yönlendiricileri gibi dosya sistemi işlemleri için sağlanır. Bu parametre olabilir NULL.

Schannel SSP kullanılırken bu parametre kullanılmaz ve olarak NULLayarlanmalıdır.

pAuthData[in, optional]

Pakete özgü verilerin işaretçisi. Bu parametre, NULLbu güvenlik paketi için varsayılan kimlik bilgilerinin kullanılması gerektiğini gösteren olabilir. Sağlanan kimlik bilgilerini kullanmak için bu parametrede bu kimlik bilgilerini içeren bir SEC_WINNT_AUTH_IDENTITY yapısı geçirin. RPC çalışma süresi , RpcBindingSetAuthInfo'da sağlanan her şeyi geçirir.

Schannel SSP kullanırken, kullanılacak protokolü ve çeşitli özelleştirilebilir kanal özellikleri için ayarları gösteren bir SCH_CREDENTIALS yapısı belirtin.

pGetKeyFn[in, optional]

Bu parametre kullanılmaz ve olarak NULLayarlanmalıdır.

pvGetKeyArgument[in, optional]

Bu parametre kullanılmaz ve olarak NULLayarlanmalıdır.

phCredential[out]

Kimlik bilgisi tanıtıcısını almak için CredHandle yapısının işaretçisi.

ptsExpiry[out, optional]

Döndürülen kimlik bilgilerinin süresinin dolmak üzere olduğu zamanı alan bir TimeStamp yapısının işaretçisi. Bu TimeStamp yapısında döndürülen değer kısıtlanmış temsile bağlıdır. Güvenlik paketinin bu değeri yerel saatle döndürmesi gerekir.

Schannel SSP kullanılırken bu parametre isteğe bağlıdır. Kimlik doğrulaması için kullanılacak kimlik bilgisi bir sertifika olduğunda, bu parametre bu sertifika için süre sonu süresini alır. Hiçbir sertifika sağlanmadıysa, maksimum zaman değeri döndürülür.

Dönüş değeri

İşlev başarılı olursa işlevi döndürür SEC_E_OK.

İşlev başarısız olursa aşağıdaki hata kodlarından birini döndürür.

İade kodu	Açıklama
SEC_E_INSUFFICIENT_MEMORY	İstenen eylemi tamamlamak için yeterli bellek yok.
SEC_E_INTERNAL_ERROR	SSPI hata koduyla eşleşmeyen bir hata oluştu.
SEC_E_NO_CREDENTIALS	Kısıtlanmış temsilde kullanılabilir kimlik bilgisi yok.
SEC_E_NOT_OWNER	İşlevi çağıranın gerekli kimlik bilgileri yok.
SEC_E_SECPKG_NOT_FOUND	İstenen güvenlik paketi yok.
SEC_E_UNKNOWN_CREDENTIALS	Pakete sağlanan kimlik bilgileri tanınmadı.

Açıklamalar

AcquireCredentialsHandle (Schannel) işlevi, belirli bir kısıtlanmış temsilci tarafından kullanıldığı gibi bir sorumlunun kimlik bilgilerine kullanıcı veya istemci gibi bir tanıtıcı döndürür. Bu, önceden var olan kimlik bilgilerinin tanıtıcısı olabilir veya işlev yeni bir kimlik bilgileri kümesi oluşturup döndürebilir. Bu tanıtıcı, AcceptSecurityContext (Schannel) ve InitializeSecurityContext (Schannel) işlevlerine yapılan sonraki çağrılarda kullanılabilir.

Genel olarak , AcquireCredentialsHandle (Schannel), bir işlemin aynı bilgisayarda oturum açmış diğer kullanıcıların kimlik bilgilerine tanıtıcı almasına izin vermez. Ancak , SE_TCB_NAMEayrıcalığına sahip bir arayan, söz konusu oturumun kimlik bilgilerine bir tanıtıcı almak için mevcut oturum açma belirtecinin oturum açma tanımlayıcısını (LUID) belirtme seçeneğine sahiptir. Bu genellikle, oturum açmış bir kullanıcı adına işlem yapması gereken çekirdek modu modülleri tarafından kullanılır.

Bir paket, RPC çalışma zamanı aktarımı tarafından sağlanan pGetKeyFn içindeki işlevi çağırabilir. Aktarım, kimlik bilgilerini almak için geri çağırmayı desteklemiyorsa, bu parametre olmalıdır NULL.

Çekirdek modu arayanları için aşağıdaki farklara dikkat edilmelidir:

• İki dize parametresi Unicode dizeleri olmalıdır.
• Arabellek değerleri havuzdan değil işlem sanal belleğinde ayrılmalıdır.

Döndürülen kimlik bilgilerini kullanmayı bitirdiğinizde, FreeCredentialsHandle işlevini çağırarak kimlik bilgileri tarafından kullanılan belleği boşaltın.

Gereksinimler

Gereksinim	Değer
Desteklenen en düşük düzeydeki istemci	Windows XP [yalnızca masaüstü uygulamaları]
Desteklenen en düşük sunucu	Windows Server 2003 [yalnızca masaüstü uygulamaları]
Başlık	Sspi.h (Security.h dahil)
Kütüphane	Secur32.lib
DLL	Secur32.dll
Unicode ve ANSI adları	AcquireCredentialsHandleW (Unicode) ve AcquireCredentialsHandleA (ANSI)

Ayrıca bkz.

AcceptSecurityContext (Schannel)

FreeCredentialsHandle

InitializeSecurityContext (Schannel)

SCH_CREDENTIALS

SSPI İşlevleri