CryptAcquireContextA 함수(wincrypt.h)
이 함수는 먼저
dwFlags적절한 설정을 사용하면 이 함수는 키 컨테이너를 만들고 삭제할 수도 있으며 프라이빗 키에 대한 액세스가 필요하지 않은 경우 임시 키 컨테이너를 사용하여 CSP에 대한 액세스를 제공할 수 있습니다.
통사론
BOOL CryptAcquireContextA(
[out] HCRYPTPROV *phProv,
[in] LPCSTR szContainer,
[in] LPCSTR szProvider,
[in] DWORD dwProvType,
[in] DWORD dwFlags
);
매개 변수
[out] phProv
CSP의 핸들에 대한 포인터입니다. CSP 사용을 마쳤으면 CryptReleaseContext 함수를 호출하여 핸들을 해제합니다.
[in] szContainer
키 컨테이너 이름입니다. CSP에 대한 키 컨테이너를 식별하는 null로 끝나는 문자열입니다. 이 이름은 키를 저장하는 데 사용되는 메서드와 독립적입니다. 일부 CSP는 키 컨테이너를 내부적으로(하드웨어에) 저장하고, 일부는 시스템 레지스트리를 사용하고, 다른 CSP는 파일 시스템을 사용합니다. 대부분의 경우
szContainer 매개 변수의 사용에 대한 자세한 내용은 비고를 참조하세요.
[in] szProvider
사용할 CSP의 이름을 포함하는 null로 끝나는 문자열입니다.
이 매개 변수가 NULL
애플리케이션은 CryptGetProvParam 함수를 사용하여 dwParam 매개 변수에서 PP_NAME CSP 값을 읽어 사용 중인 CSP의 이름을 가져올 수 있습니다.
기본 CSP는 운영 체제 릴리스 간에 변경될 수 있습니다. 다른 운영 체제 플랫폼에서 상호 운용성을 보장하려면 기본 CSP를 사용하는 대신 이 매개 변수를 사용하여 CSP를 명시적으로 설정해야 합니다.
[in] dwProvType
획득할 공급자의 형식을 지정합니다. 정의된 공급자 형식은 암호화 공급자 형식
[in] dwFlags
값에 플래그를 지정합니다. 이 매개 변수는 일반적으로 0으로 설정되지만 일부 애플리케이션은 다음 플래그 중 하나 이상을 설정합니다.
| 값 | 의미 |
|---|---|
|
이 옵션은 임시 키를 사용하는 애플리케이션 또는 해시, 암호화및 디지털 서명 확인을 수행하는 애플리케이션과 같이 지속형 프라이빗 키에 액세스할 필요가 없는 애플리케이션을 위한 것입니다. 서명을 만들거나 메시지를 암호 해독하는 애플리케이션만 프라이빗 키액세스해야 합니다. 대부분의 경우 이 플래그를 설정해야 합니다.
파일 기반 CSP의 경우 이 플래그가 설정되면 szContainer 매개 변수를 NULL설정해야 합니다. 애플리케이션은 퍼블릭/프라이빗 키 쌍의 지속형 프라이빗 키에 액세스할 수 없습니다. 이 플래그를 설정하면 임시 스마트 카드 CSP와 같은 하드웨어 기반 CSP의 경우 CryptAcquireContext 호출되면 많은 CSP는 키 컨테이너프라이빗 키에 대한 액세스 권한을 부여하기 전에 소유 사용자의 입력이 필요합니다. 예를 들어 프라이빗 키를 암호화할 수 있으므로 사용하기 전에 사용자의 암호가 필요합니다. 그러나 CRYPT_VERIFYCONTEXT 플래그를 지정하는 경우 프라이빗 키에 대한 액세스가 필요하지 않으며 사용자 인터페이스를 무시할 수 있습니다. |
|
szContainer지정한 이름으로 새 키 컨테이너를 만듭니다. |
|
기본적으로 키 및 키 컨테이너는 사용자 키로 저장됩니다. 기본 공급자의 경우 이는 사용자 키 컨테이너가 사용자의 프로필에 저장됨을 의미합니다. 관리자가 이 플래그 없이 만든 키 컨테이너는 키 컨테이너를 만드는 사용자와 관리 권한이 있는 사용자만 액세스할 수 있습니다.
Windows XP: 관리자가 이 플래그 없이 만든 키 컨테이너는 키 컨테이너 및 로컬 시스템 계정을 만드는 사용자만 액세스할 수 있습니다. 관리자가 아닌 사용자가 이 플래그 없이 만든 키 컨테이너는 키 컨테이너 및 로컬 시스템 계정을 만드는 사용자만 액세스할 수 있습니다. CRYPT_MACHINE_KEYSET 플래그를 다른 모든 플래그와 결합하여 관심 있는 키 컨테이너가 컴퓨터 키 컨테이너이고 CSP가 이를 처리함을 나타낼 수 있습니다. 기본 공급자의 경우 키 컨테이너를 만든 컴퓨터에 키가 로컬로 저장됨을 의미합니다. 키 컨테이너가 컴퓨터 컨테이너인 경우 컴퓨터 컨테이너를 참조하는 CryptAcquireContext 대한 모든 호출과 함께 CRYPT_MACHINE_KEYSET 플래그를 사용해야 합니다. CryptSetProvParam사용하여 컨테이너에 대한 액세스 권한을 부여하지 않는 한 관리자가 CRYPT_MACHINE_KEYSET 사용하여 만든 키 컨테이너는 작성자와 관리자 권한이 있는 사용자만 액세스할 수 있습니다. Windows XP: CryptSetProvParam사용하여 컨테이너에 대한 액세스 권한을 부여하지 않는 한 관리자가 CRYPT_MACHINE_KEYSET 사용하여 만든 키 컨테이너는 작성자 및 로컬 시스템 계정에서만 액세스할 수 있습니다. CryptSetProvParam사용하여 컨테이너에 대한 액세스 권한을 부여하지 않는 한 관리자가 아닌 사용자가 CRYPT_MACHINE_KEYSET 사용하여 만든 키 컨테이너는 작성자 및 로컬 시스템 계정에서만 액세스할 수 있습니다. CRYPT_MACHINE_KEYSET 플래그는 사용자가 대화형으로 로그온하지 않은 서비스 또는 사용자 계정에서 액세스할 때 유용합니다. 키 컨테이너를 만들 때 대부분의 CSP는 |
|
szContainer지정된 키 컨테이너 삭제합니다. 이 플래그를 설정하면 phProv 반환된 값이 정의되지 않으므로 나중에 CryptReleaseContext 함수를 호출할 필요가 없습니다. |
|
애플리케이션은 CSP가 이 컨텍스트대한 UI(사용자 인터페이스)를 표시하지 않도록 요청합니다. CSP가 작동할 UI를 표시해야 하는 경우 호출이 실패하고 NTE_SILENT_CONTEXT 오류 코드가 마지막 오류로 설정됩니다. 또한 CRYPT_SILENT 플래그를 사용하여 얻은 컨텍스트가 있는 CRYPT_USER_PROTECTED 플래그를 사용하여 CryptGenKey CRYPT_SILENT CSP에서 UI를 표시할 수 없는 애플리케이션에 사용하기 위한 것입니다. |
|
해시 및 대칭 키 작업에 사용할 수 있지만 PIN을 사용하여 스마트 카드에 인증해야 하는 작업에는 사용할 수 없는 스마트 카드 CSP의 컨텍스트를 가져옵니다. 이 유형의 컨텍스트는 CryptSetProvParam사용하여 PIN을 설정하는 등 빈 스마트 카드에서 작업을 수행하는 데 가장 자주 사용됩니다. 이 플래그는 스마트 카드 CSP에서만 사용할 수 있습니다.
Windows Server 2003 및 Windows XP: 이 플래그는 지원되지 않습니다. |
반환 값
함수가 성공하면 함수는 0이 아닌 값(TRUE)을 반환합니다.
함수가 실패하면 0(FALSE)을 반환합니다. 확장 오류 정보는 GetLastError호출합니다.
NTE에 의해 앞에 있는 오류 코드는 사용 중인 특정 CSP에 의해 생성됩니다. Winerror.h에 정의된 몇 가지 가능한 오류 코드는 다음과 같습니다.
| 반환 코드/값 | 묘사 |
|---|---|
|
일부 CSP는 CRYPT_DELETEKEYSET 플래그 값이 설정되고 다른 스레드 또는 프로세스 이 키 컨테이너사용하는 경우 이 오류를 설정합니다. |
|
사용자의 프로필이 로드되지 않아 찾을 수 없습니다. 이 문제는 애플리케이션에서 사용자(예: IUSR_ComputerName 계정)를 가장할 때 발생합니다. |
|
매개 변수 중 하나에 유효하지 않은 값이 포함되어 있습니다. 이는 가장 자주 유효하지 않은 포인터입니다. |
|
운영 체제가 작업 중에 메모리가 부족합니다. |
|
dwFlags 매개 변수에는 유효하지 않은 값이 있습니다. |
|
개인 키가 암호화된 이후 사용자 암호가 변경되었습니다. |
|
키 컨테이너를 열 수 없습니다. 이 오류의 일반적인 원인은 키 컨테이너가 존재하지 않는다는 것입니다. 키 컨테이너를 만들려면 CRYPT_NEWKEYSET 플래그를 사용하여 CryptAcquireContext 호출합니다. 이 오류 코드는 기존 키 컨테이너에 대한 액세스가 거부되었음을 나타낼 수도 있습니다. CryptSetProvParam사용하여 키 집합 작성자가 컨테이너에 대한 액세스 권한을 부여할 수 있습니다. |
|
szContainer 또는 szProvider 매개 변수는 유효하지 않은 값으로 설정됩니다. |
|
dwProvType 매개 변수의 값이 범위를 벗어났습니다. 모든 공급자 형식은 1부터 999까지여야 합니다. |
|
공급자 DLL 서명을 확인할 수 없습니다. DLL 또는 디지털 서명이 변조되었습니다. |
|
dwFlags 매개 변수는 CRYPT_NEWKEYSET 키 컨테이너가 이미 있습니다. |
|
szContainer 키 컨테이너가 발견되었지만 손상되었습니다. |
|
요청된 공급자가 없습니다. |
|
작업 중에 CSP 메모리가 부족합니다. |
|
공급자 DLL 파일이 없거나 현재 경로에 없습니다. |
|
dwProvType 지정된 공급자 형식이 손상되었습니다. 이 오류는 사용자 기본 CSP 목록 또는 컴퓨터 기본 CSP 목록과 관련이 있습니다. |
|
dwProvType 지정된 공급자 형식이 찾은 공급자 형식과 일치하지 않습니다. 이 오류는 szProvider 실제 CSP 이름을 지정하는 경우에만 발생할 수 있습니다. |
|
dwProvType지정된 공급자 형식에 대한 항목이 없습니다. |
|
공급자 DLL 파일을 로드하거나 초기화하지 못했습니다. |
|
서명을 확인하기 전에 DLL 파일 이미지를 로드하는 동안 오류가 발생했습니다. |
발언
szContainer 매개 변수는 키를 보유하는 데 사용되는 컨테이너의 이름을 지정합니다. 각 컨테이너에는 하나의 키가 포함될 수 있습니다. 키를 만들 때 기존 컨테이너의 이름을 지정하면 새 키가 이전 컨테이너를 덮어쓰게 됩니다.
CSP 이름과 키 컨테이너 이름의 조합은 시스템의 단일 키를 고유하게 식별합니다. 한 애플리케이션이 키 컨테이너를 사용하는 동안 키 컨테이너를 수정하려고 하면 예측할 수 없는 동작이 발생할 수 있습니다.
szContainer 매개 변수를 NULL설정하면 기본 키 컨테이너 이름이 사용됩니다. 이러한 방식으로 Microsoft 소프트웨어 CSP가 호출되면 CryptAcquireContext 함수가 호출 될 때마다 새 컨테이너가 만들어집니다. 그러나 이와 관련하여 다른 CSP가 다르게 동작할 수 있습니다. 특히 CSP에는 CSP에 액세스하는 모든 애플리케이션에서 공유하는 단일 기본 컨테이너가 있을 수 있습니다. 따라서 애플리케이션은 기본 키 컨테이너를 사용하여 프라이빗 키를 저장해서는 안 됩니다. 대신 dwFlags 매개 변수에 CRYPT_VERIFYCONTEXT 플래그를 전달하여 키 스토리지를 방지하거나 다른 애플리케이션에서 사용할 가능성이 없는 애플리케이션별 컨테이너를 사용합니다.
애플리케이션은 CryptGetProvParam 함수를 사용하여 PP_CONTAINER 값을 읽어 사용 중인 키 컨테이너의 이름을 가져올 수 있습니다.
성능상의 이유로
- 해시를 만들고 있습니다.
- 데이터를 암호화하거나 암호 해독하는 대칭 키를 생성합니다.
- 데이터를 암호화하거나 암호 해독하기 위해 해시에서 대칭 키를 파생합니다.
- 서명을 확인하고 있습니다. CryptImportKey 또는 CryptImportPublicKeyInfo사용하여 PUBLICKEYBLOB 또는 인증서에서 공개 키를 가져올 수 있습니다. 공개 키만 가져오려는 경우 CRYPT_VERIFYCONTEXT 플래그를 사용하여 컨텍스트를 가져올 수 있습니다.
- 대칭 키를 내보낼 계획이지만 암호화 컨텍스트의 수명 내에서 가져오지는 않습니다. 마지막 두 시나리오에 대한 공개 키만 가져오려는 경우 CRYPT_VERIFYCONTEXT 플래그를 사용하여 컨텍스트를 가져올 수 있습니다.
- 프라이빗 키 작업을 수행하지만 키 컨테이너에 저장된 지속형 프라이빗 키를 사용하지는 않습니다.
예제
다음 예제에서는 암호화 컨텍스트를 획득하고 키 컨테이너의 퍼블릭/프라이빗 키 쌍에 액세스하는 방법을 보여 줍니다. 요청된 키 컨테이너가 없으면 생성됩니다.
이 예제의 전체 컨텍스트를 포함하는 예제는 C 프로그램 예제: 키 컨테이너 만들기 및 키 생성참조하세요. 추가 예제는 C 프로그램 예제: CryptAcquireContext사용합니다.
//-------------------------------------------------------------------
// Declare and initialize variables.
HCRYPTPROV hCryptProv = NULL; // handle for a cryptographic
// provider context
LPCSTR UserName = "MyKeyContainer"; // name of the key container
// to be used
//-------------------------------------------------------------------
// Attempt to acquire a context and a key
// container. The context will use the default CSP
// for the RSA_FULL provider type. DwFlags is set to zero
// to attempt to open an existing key container.
if(CryptAcquireContext(
&hCryptProv, // handle to the CSP
UserName, // container name
NULL, // use the default provider
PROV_RSA_FULL, // provider type
0)) // flag values
{
printf("A cryptographic context with the %s key container \n",
UserName);
printf("has been acquired.\n\n");
}
else
{
//-------------------------------------------------------------------
// An error occurred in acquiring the context. This could mean
// that the key container requested does not exist. In this case,
// the function can be called again to attempt to create a new key
// container. Error codes are defined in Winerror.h.
if (GetLastError() == NTE_BAD_KEYSET)
{
if(CryptAcquireContext(
&hCryptProv,
UserName,
NULL,
PROV_RSA_FULL,
CRYPT_NEWKEYSET))
{
printf("A new key container has been created.\n");
}
else
{
printf("Could not create a new key container.\n");
exit(1);
}
}
else
{
printf("A cryptographic service handle could not be "
"acquired.\n");
exit(1);
}
} // End of else.
//-------------------------------------------------------------------
// A cryptographic context and a key container are available. Perform
// any functions that require a cryptographic provider handle.
//-------------------------------------------------------------------
// When the handle is no longer needed, it must be released.
if (CryptReleaseContext(hCryptProv,0))
{
printf("The handle has been released.\n");
}
else
{
printf("The handle could not be released.\n");
}
메모
wincrypt.h 헤더는 CRYptAcquireContext를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입대한
요구 사항
| 요구 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | wincrypt.h |
| 라이브러리 | Advapi32.lib |
| DLL | Advapi32.dll |
참고 항목
암호화 서비스 공급자