CredUICmdLinePromptForCredentialsA 함수(wincred.h)

  • 아티클

CredUICmdLinePromptForCredentials 함수는 명령줄(콘솔) 애플리케이션에서 작업하는 사용자의 자격 증명 정보를 묻는 메시지를 표시하고 수락합니다. 사용자가 입력한 이름과 암호는 확인을 위해 호출 애플리케이션에 다시 전달됩니다.

구문

CREDUIAPI DWORD CredUICmdLinePromptForCredentialsA(
  [in]           PCSTR       pszTargetName,
  [in]           PCtxtHandle pContext,
  [in, optional] DWORD       dwAuthError,
  [in, out]      PSTR        UserName,
  [in]           ULONG       ulUserBufferSize,
  [in, out]      PSTR        pszPassword,
  [in]           ULONG       ulPasswordBufferSize,
  [in, out]      PBOOL       pfSave,
  [in]           DWORD       dwFlags
);

매개 변수

[in] pszTargetName

자격 증명의 대상 이름(일반적으로 서버 이름)이 포함된 null로 끝나는 문자열에 대한 포인터입니다. DFS 연결의 경우 이 문자열은 ServerNameShareName\ 형식입니다. pszTargetName 매개 변수는 대상 정보를 식별하는 데 사용되며 자격 증명을 저장하고 검색하는 데 사용됩니다.

[in] pContext

현재 예약되어 있으며 NULL이어야 합니다.

[in, optional] dwAuthError

자격 증명을 묻는 메시지가 필요한 이유를 지정합니다. 호출자는 대화 상자가 특정 오류를 수용할 수 있도록 다른 인증 호출에서 반환된 이 Windows 오류 매개 변수를 전달할 수 있습니다. 예를 들어 암호가 만료된 상태 코드가 전달되면 대화 상자에서 사용자에게 계정의 암호를 변경하라는 메시지를 표시합니다.

[in, out] UserName

자격 증명 사용자 이름을 포함하는 null로 끝나는 문자열에 대한 포인터입니다. pszUserName에 길이가 0이 아닌 문자열을 지정하면 사용자에게 암호에 대한 메시지만 표시됩니다. 사용자 이름/암호 이외의 자격 증명의 경우 자격 증명의 마샬링된 형식을 전달할 수 있습니다. 이 문자열은 CredMarshalCredential을 호출하여 만듭니다.

이 함수는 사용자가 제공한 이름을 이 버퍼에 기록하여 최대 ulUserNameMaxChars 문자를 복사합니다. 이 형식의 문자열은 CredUIParseUsername 함수를 호출하여 사용자 이름/암호 형식으로 변환할 수 있습니다. 마샬링된 형식의 문자열은 SSP( 보안 지원 공급자 )에 직접 전달할 수 있습니다.

CREDUI_FLAGS_DO_NOT_PERSIST 플래그를 지정하지 않으면 이 매개 변수에 반환된 값은 CredUIParseUsername에 전달하는 것 외에는 검사, 인쇄 또는 유지해서는 안 되는 폼입니다. CredUIParseUsername의 후속 결과는 WNetAddConnection 또는 SSP API와 같은 클라이언트 쪽 인증 API에만 전달할 수 있습니다.

[in] ulUserBufferSize

종료 null 문자를 포함하여 pszUserName에 복사할 수 있는 최대 문자 수입니다.

참고 CREDUI_MAX_USERNAME_LENGTH 종료 null 문자를 포함하지 않습니다.
 

[in, out] pszPassword

자격 증명의 암호를 포함하는 null로 끝나는 문자열에 대한 포인터입니다. pszPassword에 길이가 0이 아닌 문자열을 지정하면 암호 매개 변수가 문자열로 미리 채워집니다.

이 함수는 사용자가 제공한 암호를 이 버퍼에 기록하여 최대 ulPasswordMaxChars 문자를 복사합니다. CREDUI_FLAGS_DO_NOT_PERSIST 플래그를 지정하지 않으면 이 매개 변수에 반환된 값은 WNetAddConnection 또는 SSP 함수와 같은 클라이언트 쪽 인증 함수에 전달하는 것 외에는 검사, 인쇄 또는 유지해서는 안 되는 폼입니다.

암호 사용을 마쳤으면 SecureZeroMemory 함수를 호출하여 메모리에서 암호를 지웁 암호 보호에 대한 자세한 내용은 암호 처리를 참조하세요.

[in] ulPasswordBufferSize

종료 null 문자를 포함하여 pszPassword에 복사할 수 있는 최대 문자 수입니다.

참고 CREDUI_MAX_PASSWORD_LENGTH 종료 null 문자를 포함하지 않습니다.
 

[in, out] pfSave

저장 메시지의 초기 상태를 지정하고 사용자가 명령 프롬프트에 응답한 후 저장 메시지의 상태를 수신하는 BOOL에 대한 포인터입니다. pfSave가 NULL이 아니고 CredUIPromptForCredentials가 NO_ERROR 반환하는 경우 pfSave는 저장 메시지의 상태를 반환합니다. CREDUI_FLAGS_PERSIST 플래그를 지정하면 저장 메시지가 표시되지 않지만 "y"로 간주됩니다. CREDUI_FLAGS_DO_NOT_PERSIST 플래그를 지정하고 CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX 지정하지 않으면 저장 메시지가 표시되지 않지만 "n"으로 간주됩니다.

[in] dwFlags

이 함수에 대한 특수 동작을 지정하는 DWORD 값입니다. 이 값은 다음 값 중 0개 이상의 비트 OR 조합일 수 있습니다.

값 의미
CREDUI_FLAGS_ALWAYS_SHOW_UI
 자격 증명 관리자의 기존 자격 증명에서 자격 증명을 반환할 수 있는 경우 사용자 인터페이스를 표시합니다. 이 플래그는 CREDUI_FLAGS_GENERIC_CREDENTIALS 지정되고 CREDUI_FLAGS_GENERIC_CREDENTIALS 함께만 사용되는 경우에만 허용됩니다.
CREDUI_FLAGS_DO_NOT_PERSIST
 저장 메시지를 표시하거나 자격 증명을 저장하지 마세요.

CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX 전달하여 저장 메시지만 표시하고 결과를 pfSave로 반환할 수도 있습니다.
CREDUI_FLAGS_EXCLUDE_CERTIFICATES
 사용자 이름/암호를 묻는 메시지를 표시합니다. pszUserName 매개 변수를 지정하면 사용자 이름이 생략됩니다. 자격 증명이 유지되면 전달된 사용자 이름을 자격 증명과 함께 저장합니다.
CREDUI_FLAGS_EXPECT_CONFIRMATION
 호출자가 CredUIConfirmCredentials 를 호출하여 반환된 자격 증명이 실제로 유효한지 여부를 확인하도록 지정합니다. 이렇게 하면 유효하지 않은 자격 증명이 자격 증명 관리자에 저장되지 않습니다. CREDUI_FLAGS_DO_NOT_PERSIST 지정하지 않는 한 이 플래그를 지정합니다.
CREDUI_FLAGS_GENERIC_CREDENTIALS
 사용자가 입력한 자격 증명을 일반 자격 증명으로 간주합니다.
CREDUI_FLAGS_INCORRECT_PASSWORD
 이 플래그는 자동으로 무시합니다.
CREDUI_FLAGS_PERSIST
 저장 메시지를 표시하지 말고 사용자가 "y"라고 대답한 것처럼 자격 증명을 저장합니다.
CREDUI_FLAGS_REQUEST_ADMINISTRATOR
 이 플래그는 자동으로 무시합니다.
CREDUI_FLAGS_REQUIRE_CERTIFICATE
 향후 사용을 위해 예약됨; 이 플래그를 전달하지 마세요.
CREDUI_FLAGS_REQUIRE_SMARTCARD
 스마트 카드 사용하고 PIN을 묻는 메시지를 표시합니다. 둘 이상의 스마트 카드 사용할 수 있는 경우 그 중 하나를 선택합니다. pszUserName 매개 변수가 비어 있지 않은 문자열을 전달하는 경우 문자열은 스마트 카드 중 하나에서 인증서와 연결된 UPN과 일치해야 합니다. 문자열이 인증서의 전체 UPN과 일치하거나 문자열이 인증서의 UPN에 있는 at 기호(@)의 왼쪽 부분과 일치하는 경우 UPN이 일치합니다. 일치하는 항목이 있으면 일치하는 스마트 카드 선택됩니다.
CREDUI_FLAGS_SERVER_CREDENTIAL
 이 플래그는 인증이 실패할 경우 대화 상자를 미리 채우기 위해 일치하는 자격 증명을 찾는 데만 의미가 있습니다. 이 플래그를 지정하면 와일드카드 자격 증명이 일치하지 않습니다. 자격 증명을 작성할 때는 아무런 효과가 없습니다. CredUI는 와일드카드 문자를 포함하는 자격 증명을 만들지 않습니다. 발견된 모든 항목은 사용자가 명시적으로 만들거나 RAS 연결을 만들 때와 같이 프로그래밍 방식으로 생성되었습니다.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX
 사용자가 "y"라고 대답하면 저장 메시지를 표시하고 pfSave out 매개 변수에 TRUE를 반환하고 사용자가 "n"에 대답하면 FALSE를 반환합니다. 이 플래그를 사용하려면 CREDUI_FLAGS_DO_NOT_PERSIST 지정해야 합니다.
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS
 자격 증명은 실행 자격 증명입니다. pszTargetName 매개 변수는 실행 중인 명령 또는 프로그램의 이름을 지정합니다. 프롬프트 목적으로만 사용됩니다.

반환 값

반환 값은 DWORD 이며 다음 값 중 하나일 수 있습니다.

값 Description
ERROR_INVALID_FLAGS
 이 상태 유효하지 않은 플래그 조합에 대해 반환됩니다.
ERROR_INVALID_PARAMETER
 pszTargetName이 NULL이거나, 빈 문자열이거나, CREDUI_MAX_DOMAIN_LENGTH 이상이거나, pUiInfo가 NULL이 아니고 가리키는 CredUI_INFO 구조체가 다음 요구 사항 중 하나를 충족하지 못했습니다.
  • cbSize 멤버는 하나여야 합니다.
  • hbmBanner 멤버가 NULL이 아니면 OBJ_BITMAP 형식이어야 합니다.
  • pszMessageText 멤버가 NULL이 아니면 CREDUI_MAX_MESSAGE_LENGTH 초과해서는 안 됩니다.
  • pszCaptionText 멤버가 NULL이 아니면 CREDUI_MAX_CAPTION_LENGTH 초과해서는 안 됩니다.
ERROR_NO_SUCH_LOGON_SESSION
 자격 증명 관리자를 사용할 수 없습니다. 일반적으로 이 오류는 CredUICmdLinePromptForCredentials 를 호출하고 CREDUI_FLAGS_DO_NOT_PERSIST 플래그를 전달하여 처리됩니다.
NO_ERROR
 사용자가 확인을 선택했습니다. pszUserName, pszPassword 및 pfSave 변수는 앞에서 설명한 값을 반환합니다.

설명

CREDUI_FLAGS_REQUIRE_SMARTCARD, CREDUI_FLAGS_REQUIRE_CERTIFICATE 및 CREDUI_FLAGS_EXCLUDE_CERTIFICATE 플래그는 상호 배타적입니다.

CREDUI_FLAGS_DO_NOT_PERSIST 지정한 경우 pszTargetName을 지정하거나 uiInfo-pszMessageText> 및 uiInfo-pszCaption>을 지정해야 합니다.

CREDUI_FLAG_USERNAME_TARGET_CREDENTIALS 및 CREDUI_FLAGS_GENERIC_CREDENTIALS 플래그는 상호 배타적입니다. 둘 다 지정하지 않으면 자격 증명은 도메인 자격 증명입니다.

CREDUI_FLAGS_GENERIC_CREDENTIALS 지정하지 않았거나 CREDUI_FLAGS_COMPLETE_USERNAME 지정한 경우 형식화된 이름은 구문이 선택됩니다. 선택된 구문은 CredUIParseUserName에서 암시한 것과 동일한 규칙이 사용됨을 의미합니다. 형식화된 이름이 유효하지 않으면 사용자에게 유효한 이름을 입력하라는 메시지가 표시됩니다. 형식화된 이름의 도메인 부분이 누락된 경우 대상 이름에 따라 도메인 부분이 제공됩니다.

CREDUI_FLAGS_GENERIC_CREDENTIALS 지정하고 CREDUI_FLAGS_VALIDATE_USERNAME 지정한 경우 형식화된 이름은 구문이 선택됩니다. 형식화된 이름이 유효하지 않으면 사용자에게 유효한 이름을 입력하라는 메시지가 표시됩니다.

CREDUI_FLAGS_GENERIC_CREDENTIALS 지정되고 CREDUI_FLAGS_COMPLETE_USERNAME 또는 CREDUI_FLAGS_VALIDATE_USERNAME 지정되지 않은 경우 형식화된 이름은 어떤 방식으로든 검사되지 않습니다.

CREDUI_FLAGS_PERSIST 또는 CREDUI_FLAGS_DO_NOT_PERSIST 설정되지 않은 경우 저장 메시지가 표시되고 자격 증명이 저장되는지 여부를 제어합니다.

CREDUI_FLAGS_PROMPT_FOR_SAVE 지정한 경우 pfSave 매개 변수는 NULL이 아니어야 합니다.

CREDUI_FLAGS_REQUIRE_SMARTCARD 및 CREDUI_FLAGS_EXCLUDE_CERTIFICATES 플래그는 상호 배타적입니다. CredUICmdLinePromptForCredentials는 스마트 카드 인증서 또는 암호 기반 자격 증명에 대한 프롬프트를 지원합니다. 스마트 카드 인증서가 아니거나 단일 호출에서 둘 다에 대한 메시지를 표시하는 인증서를 지원하지 않습니다.

호출 모드

  • 호출자는 대상 리소스에 액세스하고, credui를 호출하고(대상 리소스 및 실패 상태 대한 설명을 전달하고, CredUIParseUserName을 호출하고, 대상 리소스에 다시 액세스한 다음, CredUIConfirmCredentials를 호출합니다.
  • 호출자는 CREDUI_FLAGS_DO_NOT_PERSIST 전달하여 리소스에 액세스하지 않고 자격 증명을 묻는 메시지를 표시할 수 있습니다.
대상 정보

대상 정보는 액세스할 리소스의 위치에 대한 정보입니다. 리소스에 대한 모든 잠재적 대상 이름 목록은 CredGetTargetInfo를 호출합니다. CredGetTargetInfo 는 해당 패키지 중 하나가 명명된 대상에 인증하는 데 사용된 경우 Negotiate, NTLM 또는 Kerberos 인증 패키지에 의해 캐시된 정보를 반환합니다. CredGetTargetInfo 는 대상에 대해 다음 이름의 일부 또는 전부를 반환합니다.

  • 컴퓨터의 NetBIOS 서버 이름
  • 컴퓨터의 DNS 서버 이름
  • 컴퓨터가 속한 도메인의 NetBIOS 도메인 이름
  • 컴퓨터가 속한 도메인의 DNS 도메인 이름
  • 컴퓨터가 속한 트리의 DNS 트리 이름
  • 정보를 수집한 패키지의 이름
정보가 대상 컴퓨터에 적용되지 않는 경우 이 정보가 누락될 수 있습니다. instance 작업 그룹의 구성원인 컴퓨터에는 NetBIOS 도메인 이름이 없습니다. Windows 도메인의 구성원인 컴퓨터에는 DNS 도메인 이름 또는 DNS 트리 이름이 없습니다.

자격 증명은 대상 이름에 따라 자격 증명 관리자에 저장됩니다. 각 대상 이름은 자격 증명 관리자에 이미 저장된 자격 증명과 충돌하지 않고 가능한 한 일반적으로 저장됩니다. 대상 이름으로 자격 증명을 저장하는 중요한 효과는 특정 사용자가 자격 증명 관리자에 저장된 대상당 하나의 자격 증명만 가질 수 있다는 것입니다.

참고

wincred.h 헤더는 CRedUICmdLinePromptForCredentials를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버 Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼 Windows
헤더 wincred.h
라이브러리 Credui.lib
DLL Credui.dll

추가 정보

CredGetTargetInfo

CredMarshalCredential

CredUIConfirmCredentials

CredUIParseUserName

CredUI_INFO

WNetAddConnection