InitializeSecurityContext(CredSSP) 함수

아티클
03/18/2023

InitializeSecurityContext(CredSSP) 함수는 자격 증명 핸들에서 클라이언트 쪽 아웃바운드 보안 컨텍스트를 시작합니다. 함수는 클라이언트 애플리케이션과 원격 피어 간에 보안 컨텍스트를 빌드합니다. InitializeSecurityContext(CredSSP) 는 클라이언트가 원격 피어에 전달해야 하는 토큰을 반환합니다. 피어는 CredSSP(AcceptSecurityContext) 호출을 통해 해당 토큰을 로컬 보안 구현에 제출합니다. 생성된 토큰은 모든 호출자가 불투명한 것으로 간주해야 합니다.

일반적으로 충분한 보안 컨텍스트가 설정될 때까지 InitializeSecurityContext(CredSSP) 함수가 루프에서 호출됩니다.

구문

SECURITY_STATUS SEC_ENTRY InitializeSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_opt_    SEC_CHAR       *pszTargetName,
  _In_        unsigned long  fContextReq,
  _Reserved_  unsigned long  Reserved1,
  _In_        unsigned long  TargetDataRep,
  _Inout_opt_ PSecBufferDesc pInput,
  _In_        unsigned long  Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Out_opt_   PSecBufferDesc pOutput,
  _Out_       unsigned long  *pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

매개 변수

phCredential[in, optional]

AcquireCredentialsHandle(CredSSP)에서 반환된 자격 증명에 대한 핸들입니다. 이 핸들은 보안 컨텍스트를 빌드하는 데 사용됩니다. InitializeSecurityContext(CredSSP) 함수에는 최소한 아웃바운드 자격 증명이 필요합니다.

phContext[in, optional]

CtxtHandle 구조체에 대한 포인터입니다. InitializeSecurityContext(CredSSP)에 대한 첫 번째 호출에서 이 포인터는 입니다NULL. 두 번째 호출에서 이 매개 변수는 첫 번째 호출에 의해 phNewContext 매개 변수에 반환된 부분적으로 형성된 컨텍스트에 대한 핸들에 대한 포인터입니다.

InitializeSecurityContext(CredSSP)에 대한 첫 번째 호출에서 를 지정합니다NULL. 이후 호출에서 이 함수에 대한 첫 번째 호출 후 phNewContext 매개 변수에서 받은 토큰을 지정합니다.

경고

InitializeSecurityContext(CredSSP)에 대한 동시 호출에서 동일한 컨텍스트 핸들을 사용하지 마세요. 보안 서비스 공급자의 API 구현은 스레드로부터 안전하지 않습니다.

pTargetName[in, optional]

대상 서버를 고유하게 식별하는 null로 끝나는 문자열에 대한 포인터입니다. Schannel은 이 값을 사용하여 서버 인증서를 확인합니다. 또한 Schannel은 이 값을 사용하여 연결을 다시 설치할 때 세션 캐시에서 세션을 찾습니다. 캐시된 세션은 다음 조건이 모두 충족되는 경우에만 사용됩니다.

대상 이름은 동일합니다.
캐시 항목이 만료되지 않았습니다.
함수를 호출하는 애플리케이션 프로세스는 동일합니다.
로그온 세션은 동일합니다.
자격 증명 핸들은 동일합니다.

fContextReq[in]

컨텍스트에 대한 요청을 나타내는 비트 플래그입니다. 모든 패키지가 모든 요구 사항을 지원할 수 있는 것은 아닙니다. 이 매개 변수에 사용되는 플래그에는 접두사로 ISC_REQ_(예: ISC_REQ_DELEGATE)가 있습니다.

이 매개 변수는 다음 특성 플래그 중 하나 이상일 수 있습니다.

값	의미
ISC_REQ_ALLOCATE_MEMORY `0x100`	보안 패키지는 호출자에 대한 출력 버퍼를 할당합니다. 출력 버퍼 사용을 마치면 FreeContextBuffer 함수를 호출하여 해제합니다.
ISC_REQ_CONNECTION `0x800`	보안 컨텍스트는 메시지 서식을 처리하지 않습니다.
ISC_REQ_EXTENDED_ERROR `0x4000`	오류가 발생하면 원격 당사자에게 알림이 표시됩니다.
ISC_REQ_MANUAL_CRED_VALIDATION `0x80000`	CredSSP(자격 증명 보안 지원 공급자)는 서버를 자동으로 인증해서는 안 됩니다. 이 플래그는 CredSSP를 사용할 때 항상 설정됩니다.
ISC_REQ_SEQUENCE_DETECT `0x8`	시퀀스에서 수신된 메시지를 검색합니다.
ISC_REQ_STREAM `0x8000`	스트림 지향 연결을 지원합니다.
ISC_REQ_USE_SUPPLIED_CREDS `0x80`	CredSSP는 클라이언트에 대한 자격 증명을 자동으로 제공하려고 시도해서는 안 됩니다.
ISC_REQ_DELEGATE `0x1`	사용자의 자격 증명을 서버에 위임해야 했음을 나타냅니다. 이 플래그를 지정하지 않으면 빈 자격 증명 집합이 서버에 위임됩니다. Windows Server 2008 및 Windows Vista: 이 플래그는 필수입니다.
ISC_REQ_MUTUAL_AUTH `0x2`	서버 인증이 필요하지 않음을 나타냅니다. 이 플래그를 지정하지 않으면 위임 정책이 계속 적용됩니다. Windows Server 2008 및 Windows Vista: 이 플래그는 무시됩니다.

요청된 특성은 클라이언트에서 지원되지 않을 수 있습니다. 자세한 내용은 pfContextAttr 매개 변수를 참조하세요.

다양한 특성에 대한 자세한 내용은 컨텍스트 요구 사항을 참조하세요.

Reserved1[in]

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

TargetDataRep[in]

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

pInput[in, out, optional]

패키지에 대한 입력으로 제공된 버퍼에 대한 포인터를 포함하는 SecBufferDesc 구조체에 대한 포인터입니다. 서버에서 클라이언트 컨텍스트를 시작하지 않는 한 이 매개 변수의 값은 함수에 대한 첫 번째 호출에 있어야 NULL 합니다. 함수에 대한 후속 호출 또는 서버에서 클라이언트 컨텍스트를 시작한 경우 이 매개 변수의 값은 원격 컴퓨터에서 반환된 토큰을 보유하기에 충분한 메모리로 할당된 버퍼에 대한 포인터입니다.

초기 호출 후 이 함수를 호출할 때는 두 개의 버퍼가 있어야 합니다. 첫 번째 형식에는 SECBUFFER_TOKEN 형식이 있으며 서버에서 받은 토큰이 포함됩니다. 두 번째 버퍼에는 SECBUFFER_EMPTY 형식이 있습니다. pvBuffer 및 cbBuffer 멤버를 모두 0으로 설정합니다.

Reserved2[in]

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

phNewContext[in, out, optional]

CtxtHandle 구조체에 대한 포인터입니다. InitializeSecurityContext(CredSSP)에 대한 첫 번째 호출에서 이 포인터는 새 컨텍스트 핸들을 받습니다. 두 번째 호출에서 phNewContext 는 phContext 매개 변수에 지정된 핸들과 같을 수 있습니다. phNewContext는 되어서는 안 됩니다 NULL.

pOutput[out, optional]

SecBufferDesc 구조체에 대한 포인터입니다. 이 구조체에는 출력 데이터를 수신하는 SecBuffer 구조체에 대한 포인터가 포함됩니다. 버퍼가 입력에 SEC_READWRITE 입력된 경우 출력에 있습니다. 시스템은 요청된 경우( ISC_REQ_ALLOCATE_MEMORY 통해) 보안 토큰에 대한 버퍼를 할당하고 보안 토큰에 대한 버퍼 설명자의 주소를 채웁니다.

ISC_REQ_ALLOCATE_MEMORY 플래그를 지정하면 CredSSP는 버퍼에 대한 메모리를 할당하고 SecBufferDesc에 적절한 정보를 배치합니다.

pfContextAttr[out]

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

이 매개 변수에 사용되는 플래그에는 ISC_RET_DELEGATE 같은 ISC_RET 접두사로 지정됩니다. 유효한 값 목록은 fContextReq 매개 변수를 참조하세요.

최종 함수 호출이 성공적으로 반환될 때까지 보안 관련 특성에 대해 검사 않습니다. 보안과 관련이 없는 특성 플래그(예: ASC_RET_ALLOCATED_MEMORY 플래그)는 최종 반환 전에 확인할 수 있습니다.

참고

특정 컨텍스트 특성은 원격 피어와 협상하는 동안 변경 될 수 있습니다.

ptsExpiry[out, optional]

컨텍스트의 만료 시간을 수신하는 TimeStamp 구조체에 대한 포인터입니다. 보안 패키지는 항상 로컬 시간에 이 값을 반환하는 것이 좋습니다. 이 매개 변수는 선택 사항이며 NULL 단기 클라이언트에 대해 전달되어야 합니다.

반환 값

함수가 성공하면 다음 성공 코드 중 하나를 반환합니다.

반환 코드	설명
SEC_E_INCOMPLETE_MESSAGE	전체 메시지에 대한 데이터가 유선에서 읽지 않았습니다. 이 값이 반환되면 pInput 버퍼에는 SECBUFFER_MISSINGBufferType 멤버가 있는 SecBuffer 구조체가 포함됩니다. SecBuffer의 cbBuffer 멤버는 이 함수가 성공하기 전에 함수가 클라이언트에서 읽어야 하는 추가 바이트 수를 지정합니다. 이 숫자가 항상 정확하지는 않지만 이 숫자를 사용하면 이 함수에 대한 여러 호출을 방지하여 성능을 향상시킬 수 있습니다.
SEC_E_OK	보안 컨텍스트가 성공적으로 초기화되었습니다. 다른 InitializeSecurityContext(CredSSP) 호출이 필요하지 않습니다. 함수가 출력 토큰을 반환하는 경우, 즉 pOutput의 SECBUFFER_TOKEN 길이가 0이 아니면 해당 토큰을 서버로 보내야 합니다.
SEC_I_COMPLETE_AND_CONTINUE	클라이언트는 CompleteAuthToken 을 호출한 다음 출력을 서버에 전달해야 합니다. 그런 다음 클라이언트는 반환된 토큰을 기다렸다가 다른 호출에서 InitializeSecurityContext(CredSSP)에 전달합니다.
SEC_I_COMPLETE_NEEDED	클라이언트는 메시지 빌드를 완료한 다음 CompleteAuthToken 함수를 호출해야 합니다.
SEC_I_CONTINUE_NEEDED	클라이언트는 출력 토큰을 서버에 보내고 반환 토큰을 기다려야 합니다. 클라이언트는 반환된 토큰을 InitializeSecurityContext(CredSSP)에 대한 다른 호출에서 전달합니다. 출력 토큰은 비어 있을 수 있습니다.
SEC_I_INCOMPLETE_CREDENTIALS	서버가 클라이언트 인증을 요청했지만 제공된 자격 증명에 인증서가 포함되지 않았거나 서버가 신뢰하는 인증 기관에서 인증서를 발급하지 않았습니다. 자세한 내용은 설명 부분을 참조하세요.

함수가 실패하면 함수는 다음 오류 코드 중 하나를 반환합니다.

반환 코드	설명
SEC_E_INSUFFICIENT_MEMORY	요청된 작업을 완료하는 데 사용할 수 있는 메모리가 부족합니다.
SEC_E_INTERNAL_ERROR	SSPI 오류 코드에 매핑되지 않은 오류가 발생했습니다.
SEC_E_INVALID_HANDLE	함수에 전달된 핸들이 잘못되었습니다.
SEC_E_INVALID_TOKEN	입력 토큰의 형식이 잘못되었습니다. 가능한 원인으로는 전송 중에 손상된 토큰, 잘못된 크기의 토큰 및 잘못된 보안 패키지에 전달된 토큰이 포함됩니다. 이 마지막 조건은 클라이언트와 서버가 적절한 보안 패키지를 협상하지 않은 경우에 발생할 수 있습니다.
SEC_E_LOGON_DENIED	로그온에 실패했습니다.
SEC_E_NO_AUTHENTICATING_AUTHORITY	인증을 위해 연락할 수 있는 권한은 없습니다. 인증 당사자의 도메인 이름이 잘못되었거나, 도메인에 연결할 수 없거나, 트러스트 관계 오류가 있을 수 있습니다.
SEC_E_NO_CREDENTIALS	보안 패키지에서 사용할 수 있는 자격 증명이 없습니다.
SEC_E_TARGET_UNKNOWN	대상이 인식되지 않았습니다.
SEC_E_UNSUPPORTED_FUNCTION	fContextReq 매개 변수의 값이 잘못되었습니다. 필수 플래그를 지정하지 않았거나 CredSSP에서 지원하지 않는 플래그를 지정했습니다.
SEC_E_WRONG_PRINCIPAL	인증 요청을 받은 보안 주체는 pszTargetName 매개 변수에 전달된 보안 주체와 다릅니다. 이 오류는 상호 인증에 실패했음을 나타냅니다.
SEC_E_DELEGATION_POLICY	정책은 대상 서버에 대한 자격 증명 위임을 지원하지 않습니다.
SEC_E_POLICY_NLTM_ONLY	상호 인증을 수행할 수 없는 경우 대상 서버에 대한 자격 증명 위임이 허용되지 않습니다.
SEC_E_MUTUAL_AUTH_FAILED	fContextReq 매개 변수에 ISC_REQ_MUTUAL_AUTH 플래그를 지정하면 서버 인증에 실패했습니다.

설명

호출자는 최종 컨텍스트 특성이 충분한지 여부를 결정합니다. 예를 들어 기밀성이 요청되었지만 설정할 수 없는 경우 일부 애플리케이션은 연결을 즉시 종료하도록 선택할 수 있습니다.

보안 컨텍스트의 특성이 충분하지 않은 경우 클라이언트는 DeleteSecurityContext 함수를 호출하여 부분적으로 생성된 컨텍스트를 해제해야 합니다.

클라이언트는 InitializeSecurityContext(CredSSP) 함수를 호출하여 아웃바운드 컨텍스트를 초기화합니다.

두 다리 보안 컨텍스트의 경우 호출 시퀀스는 다음과 같습니다.

클라이언트는 phContext 가 로 설정된 함수를 NULL 호출하고 버퍼 설명자를 입력 메시지로 채웁니다.
보안 패키지는 매개 변수를 검사하고 불투명 토큰을 생성하여 버퍼 배열의 TOKEN 요소에 배치합니다. fContextReq 매개 변수에 ISC_REQ_ALLOCATE_MEMORY 플래그가 포함된 경우 보안 패키지는 메모리를 할당하고 TOKEN 요소에 포인터를 반환합니다.
클라이언트는 pOutput 버퍼에 반환된 토큰을 대상 서버로 보냅니다. 그런 다음 서버는 AcceptSecurityContext(CredSSP) 함수에 대한 호출에서 토큰을 입력 인수로 전달합니다.
AcceptSecurityContext(CredSSP)는 토큰을 반환할 수 있습니다. 첫 번째 호출이 SEC_I_CONTINUE_NEEDED 반환된 경우 서버는 두 번째 CredSSP(InitializeSecurityContext) 호출을 통해 이 토큰을 클라이언트에 보냅니다.

서버가 성공적으로 응답한 경우 보안 패키지는 SEC_E_OK 반환하고 보안 세션이 설정됩니다.

함수가 오류 응답 중 하나를 반환하는 경우 서버의 응답이 수락되지 않고 세션이 설정되지 않습니다.

함수가 SEC_I_CONTINUE_NEEDED, SEC_I_COMPLETE_NEEDED 또는 SEC_I_COMPLETE_AND_CONTINUE 반환하는 경우 2단계와 3단계가 반복됩니다.

보안 컨텍스트 초기화는 fContextReq 매개 변수에 지정된 선택 사항뿐만 아니라 기본 인증 메커니즘에 따라 이 함수에 대해 둘 이상의 호출이 필요할 수 있습니다.

fContextReq 및 pfContextAttributes 매개 변수는 다양한 컨텍스트 특성을 나타내는 비트 마스크입니다. 다양한 특성에 대한 설명은 컨텍스트 요구 사항을 참조하세요. pfContextAttributes 매개 변수는 성공적인 반환에 유효하지만 최종 반환에 대해서만 컨텍스트의 보안 측면과 관련된 플래그를 검사해야 합니다. 중간 반환은 예를 들어 ISC_RET_ALLOCATED_MEMORY 플래그를 설정할 수 있습니다.

ISC_REQ_USE_SUPPLIED_CREDS 플래그가 설정된 경우 보안 패키지는 pInput 입력 버퍼에서 SECBUFFER_PKG_PARAMS 버퍼 유형을 찾아야 합니다. 일반적인 솔루션은 아니지만 적절한 경우 보안 패키지와 애플리케이션을 강력하게 페어링할 수 있습니다.

ISC_REQ_ALLOCATE_MEMORY 지정한 경우 호출자는 FreeContextBuffer 함수를 호출하여 메모리를 해제해야 합니다.

예를 들어 입력 토큰은 LAN 관리자의 과제일 수 있습니다. 이 경우 출력 토큰은 챌린지에 대한 NTLM 암호화 응답입니다.

클라이언트가 수행하는 작업은 이 함수의 반환 코드에 따라 달라집니다. 반환 코드가 SEC_E_OK 경우 두 번째 InitializeSecurityContext(CredSSP) 호출이 없으며 서버의 응답이 필요하지 않습니다. 반환 코드가 SEC_I_CONTINUE_NEEDED 경우 클라이언트는 서버의 응답으로 토큰을 예상하여 InitializeSecurityContext(CredSSP)에 대한 두 번째 호출에서 전달합니다. SEC_I_COMPLETE_NEEDED 반환 코드는 클라이언트가 메시지 빌드를 완료하고 CompleteAuthToken 함수를 호출해야 했음을 나타냅니다. SEC_I_COMPLETE_AND_CONTINUE 코드는 이러한 작업을 모두 통합합니다.

InitializeSecurityContext(CredSSP)가 첫 번째(또는 유일한) 호출에서 성공을 반환하는 경우 호출자는 인증 교환의 이후 레그에서 호출이 실패하더라도 반환된 핸들에서 DeleteSecurityContext 함수를 호출해야 합니다.

클라이언트는 성공적으로 완료 된 후 InitializeSecurityContext(CredSSP) 를 다시 호출할 수 있습니다. 이는 보안 패키지에 재인증이 원한다는 것을 나타냅니다.

커널 모드 호출자에는 다음과 같은 차이점이 있습니다. 대상 이름은 VirtualAlloc을 사용하여 가상 메모리에 할당해야 하는 유니코드 문자열입니다. 풀에서 할당해서는 안 됩니다. pInput 및 pOutput에서 전달되고 제공된 버퍼는 풀이 아닌 가상 메모리에 있어야 합니다.

함수가 SEC_I_INCOMPLETE_CREDENTIALS 반환하는 경우 AcquireCredentialsHandle(CredSSP) 함수에 전달된 r 자격 증명이 유효하고 신뢰할 수 있는 인증서를 지정했는지 검사 인증서는 서버에서 신뢰할 수 있는 인증 기관에서 발급한 클라이언트 인증 인증서여야 합니다. 서버에서 신뢰할 수 있는 CA 목록을 가져오려면 SECPKG_ATTR_ISSUER_LIST_EX 특성을 사용하여 QueryContextAttributes(CredSSP) 함수를 호출합니다.

서버가 신뢰하는 인증 기관으로부터 인증 인증서를 받은 후 클라이언트 애플리케이션은 새 자격 증명을 만듭니다. 이렇게 하려면 AcquireCredentialsHandle(CredSSP) 함수를 호출한 다음 InitializeSecurityContext(CredSSP) 를 다시 호출하고 phCredential 매개 변수에 새 자격 증명을 지정합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
헤더	Sspi.h(Security.h 포함)
라이브러리	Secur32.lib
DLL	Secur32.dll