SspiInitializeSecurityContextAsyncA 함수(sspi.h)

  • 아티클

SspiInitializeSecurityContextAsyncA 함수는 자격 증명 핸들에서 클라이언트 쪽 아웃바운드 보안 컨텍스트를 시작합니다. 함수는 클라이언트 애플리케이션과 원격 피어 간에 보안 컨텍스트를 빌드하는 데 사용됩니다. SspiInitializeSecurityContextAsyncA 는 클라이언트가 원격 피어에 전달해야 하는 토큰을 반환하며, 피어는 SspiAcceptSecurityContextAsync 호출을 통해 로컬 보안 구현에 제출합니다.

참고

이 함수는InitializeSecurityContext 함수에 대한 비동기 함수 역할을 합니다.

구문

SECURITY_STATUS SspiInitializeSecurityContextAsyncA(
  SspiAsyncContext *AsyncContext,
  PCredHandle      phCredential,
  PCtxtHandle      phContext,
  LPSTR            pszTargetName,
  unsigned long    fContextReq,
  unsigned long    Reserved1,
  unsigned long    TargetDataRep,
  PSecBufferDesc   pInput,
  unsigned long    Reserved2,
  PCtxtHandle      phNewContext,
  PSecBufferDesc   pOutput,
  unsigned long    *pfContextAttr,
  PTimeStamp       ptsExpiry
);

매개 변수

AsyncContext

비동기 호출 컨텍스트입니다.

phCredential

AcquireCredentialsHandle에서 반환된 자격 증명에 대한 핸들입니다. 이 핸들은 보안 컨텍스트를 빌드하는 데 사용됩니다.

phContext

기존 CtxtHandle 구조체에 대한 포인터입니다.

pszTargetName

컨텍스트의 대상을 나타내는 null로 끝나는 문자열에 대한 포인터입니다. 문자열 콘텐츠는 다음 표에 설명된 대로 보안 패키지 에 따라 다릅니다. 이 목록은 전체 목록이 아닙니다. 시스템에 추가 시스템 SSP 및 타사 SSP를 추가할 수 있습니다.

사용 중인 SSP 의미
다이제스트 요청된 리소스의 URI를 고유하게 식별하는 Null로 종료된 문자열입니다. 문자열은 URI에서 허용되는 문자로 구성되어야 하며 미국 ASCII 코드 집합으로 나타낼 수 있어야 합니다. 백분율 인코딩은 미국 ASCII 코드 집합 외부의 문자를 나타내는 데 사용할 수 있습니다.
Kerberos 또는 협상 SPN(서비스 사용자 이름) 또는 대상 서버의 보안 컨텍스트 입니다.
NTLM SPN(서비스 사용자 이름) 또는 대상 서버의 보안 컨텍스트 입니다.
Schannel/SSL 대상 서버를 고유하게 식별하는 Null로 종료된 문자열입니다. Schannel은 이 값을 사용하여 서버 인증서를 확인합니다. 또한 Schannel은 이 값을 사용하여 연결을 다시 설치할 때 세션 캐시에서 세션을 찾습니다. 캐시된 세션은 다음 조건이 모두 충족되는 경우에만 사용됩니다.
  • 대상 이름은 동일합니다.
  • 캐시 항목이 만료되지 않았습니다.
  • 함수를 호출하는 애플리케이션 프로세스는 동일합니다.
  • 로그온 세션은 동일합니다.
  • 자격 증명 핸들은 동일합니다.

fContextReq

컨텍스트에 대한 요청을 나타내는 비트 플래그입니다.

플래그 값 및 해당 의미 목록은 InitializeSecurityContext: fContextReq 를 참조하세요.

Reserved1

이 매개 변수는 예약되어 있으며 0으로 설정해야 합니다.

TargetDataRep

대상의 바이트 순서 지정과 같은 데이터 표현입니다. 이 매개 변수는 SECURITY_NATIVE_DREP 또는 SECURITY_NETWORK_DREP 수 있습니다.

pInput

패키지에 대한 입력으로 제공된 버퍼에 대한 포인터를 포함하는 SecBufferDesc 구조체에 대한 포인터입니다.

Reserved2

이 매개 변수는 예약되어 있으며 0으로 설정해야 합니다.

phNewContext

CtxtHandle 구조체에 대한 포인터입니다.

pOutput

출력 데이터를 수신하는 SecBuffer 구조체에 대한 포인터를 포함하는 SecBufferDesc 구조체에 대한 포인터입니다.

pfContextAttr

설정된 컨텍스트의 특성을 나타내는 비트 플래그 집합을 수신하는 변수에 대한 포인터입니다. 다양한 특성에 대한 설명은 컨텍스트 요구 사항을 참조하세요.

ptsExpiry

선택 사항입니다. 컨텍스트의 만료 시간을 수신하는 TimeStamp 구조체에 대한 포인터입니다.

반환 값

보안 컨텍스트를 설정하기 위한 비동기 요청이 실행을 위해 성공적으로 큐에 대기된 경우 SEC_E_OK 반환하고, 그렇지 않으면 큐에 대기하려고 시도하여 생성된 오류를 반환합니다. 작업의 상태 검색하려면 SspiGetAsyncCallStatus를 사용합니다.

서버에서 받은 보안 컨텍스트가 수락된 경우 SspiGetAsyncCallStatus는 아래 표에 SEC_E_OK 또는 SSPI 코드 중 하나를 반환합니다. 그렇지 않으면 호출이 아직 진행 중인 경우 SEC_I_ASYNC_CALL_PENDING 반환하거나 아래 두 번째 표에 있는 다음과 같은 심각한 오류 코드가 반환됩니다.

반환 코드
설명
SEC_I_COMPLETE_AND_CONTINUE
0x00090314L		 클라이언트는 CompleteAuthToken 을 호출하고 출력 토큰을 서버에 전달해야 합니다. 그런 다음 클라이언트는 반환된 토큰을 기다렸다가 다른 호출에서 SspiInitializeSecurityContextAsyncA에 전달합니다.
SEC_I_COMPLETE_NEEDED
0x00090313L		 클라이언트는 CompleteAuthToken을 호출하기 전에 서버에서 메시지 빌드를 완료해야 합니다.
SEC_I_CONTINUE_NEEDED
0x00090312L		 클라이언트는 출력 토큰을 서버에 보내고 반환 토큰을 기다려야 합니다. 반환된 토큰은 SspiInitializeSecurityContextAsyncA에 대한 다른 호출에서 전달됩니다. 출력 토큰은 비어 있을 수 있습니다.
SEC_I_INCOMPLETE_CREDENTIALS Schannel과 함께 사용합니다. 서버가 클라이언트 인증을 요청했으며 제공된 자격 증명에 인증서가 포함되지 않았거나 서버에서 신뢰할 수 있는 인증 기관에서 인증서를 발급하지 않았습니다.
SEC_E_INCOMPLETE_MESSAGE
0x80090318L		 전체 메시지에 대한 데이터가 유선에서 읽지 않았습니다. 이 값이 반환되면 pInput 버퍼에는 SECBUFFER_MISSING BufferType 멤버가 있는 SecBuffer 구조체가 포함됩니다. SecBuffer의 cbBuffer 멤버에는 이 함수가 성공하기 전에 함수가 클라이언트에서 읽어야 하는 추가 바이트 수를 나타내는 값이 포함되어 있습니다. 이 숫자가 항상 정확하지는 않지만 이 숫자를 사용하면 이 함수에 대한 여러 호출을 방지하여 성능을 향상시킬 수 있습니다.
SEC_E_OK
0x00000000L		 클라이언트에서 받은 보안 컨텍스트가 수락되었습니다. 함수가 출력 토큰을 생성한 경우 토큰을 서버로 보내야 합니다.

심각한 오류 코드

반환 코드
설명
SEC_E_INSUFFICIENT_MEMORY
0x80090300L		 요청된 작업을 완료하는 데 사용할 수 있는 메모리가 부족합니다.
SEC_E_INTERNAL_ERROR
0x80090304L		 SSPI 오류 코드에 매핑되지 않은 오류가 발생했습니다.
SEC_E_INVALID_HANDLE
0x80100003L		 함수에 전달된 핸들이 잘못되었습니다.
SEC_E_INVALID_TOKEN
0x80090308L		 이 오류는 전송 중에 손상된 토큰, 잘못된 크기의 토큰 또는 잘못된 보안 패키지에 전달된 토큰과 같은 형식이 잘못된 입력 토큰 때문입니다. 클라이언트와 서버가 적절한 보안 패키지를 협상하지 않은 경우 잘못된 패키지에 토큰을 전달할 수 있습니다.
SEC_E_LOGON_DENIED
0x8009030CL		 로그온에 실패했습니다.
SEC_E_NO_AUTHENTICATING_AUTHORITY
0x80090311L		 인증을 위해 연락할 수 있는 권한은 없습니다. 인증 당사자의 도메인 이름이 잘못되었거나, 도메인에 연결할 수 없거나, 트러스트 관계 오류가 있을 수 있습니다.
SEC_E_NO_CREDENTIALS
0x8009030EL		 보안 패키지에서 사용할 수 있는 자격 증명이 없습니다.
SEC_E_TARGET_UNKNOWN 대상이 인식되지 않았습니다.
SEC_E_UNSUPPORTED_FUNCTION
0x80090302L		 잘못된 컨텍스트 특성 플래그(ISC_REQ_DELEGATE 또는 ISC_REQ_PROMPT_FOR_CREDS)가 fContextReq 매개 변수에 지정되었습니다.
SEC_E_WRONG_PRINCIPAL 인증 요청을 받은 보안 주체는 pszTargetName 매개 변수에 전달된 보안 주체와 다릅니다. 이는 상호 인증에 실패했음을 나타냅니다.

설명

전체 설명은 InitializeSecurityContext 를 참조하세요.

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows 10 버전 1607 [커널 모드 드라이버만 해당]
지원되는 최소 서버 Windows Server 2016 [커널 모드 드라이버만 해당]
머리글 sspi.h

추가 정보

SspiAcceptSecurityContextAsync

SspiAcquireCredentialsHandleAsync