CryptGetProvParam 함수(wincrypt.h)
구문
BOOL CryptGetProvParam(
[in] HCRYPTPROV hProv,
[in] DWORD dwParam,
[out] BYTE *pbData,
[in, out] DWORD *pdwDataLen,
[in] DWORD dwFlags
);
매개 변수
[in] hProv
쿼리의 CSP 대상 핸들입니다. 이 핸들은 CryptAcquireContext 함수를 사용하여 만들어야 합니다.
[in] dwParam
쿼리의 특성입니다. 다음 쿼리가 정의됩니다.
| 값 | 의미 |
|---|---|
|
pbData 매개 변수의 관리자 PIN(개인 식별 번호)을 LPSTR로 반환합니다. |
|
이 상수는 사용되지 않습니다. |
|
이 상수는 사용되지 않습니다. |
|
hProv 핸들과 연결된 인증서 체인을 반환합니다. 반환된 인증서 체인은 X509_ASN_ENCODING 인코딩됩니다. |
|
null로 끝나는 CHAR 문자열인 현재 키 컨테이너의 이름입니다. 이 문자열은 사용할 키 컨테이너를 지정하기 위해 CryptAcquireContext 함수의 pszContainer 매개 변수에 전달된 문자열과 정확히 동일합니다. pszContainer 매개 변수를 읽고 기본 키 컨테이너의 이름을 확인할 수 있습니다. |
|
Microsoft CSP에서 구현되지 않습니다. 이 동작은 다른 CSP에서 구현할 수 있습니다.
Windows XP: 이 매개 변수는 지원되지 않습니다. |
|
쿼리 중인 CSP에서 지원하는 하나의 알고리즘에 대한 정보를 포함하는 PROV_ENUMALGS 구조체입니다.
이 값을 처음 읽을 때 dwFlags 매개 변수에는 CRYPT_FIRST 플래그가 포함되어야 합니다. 이렇게 하면 이 함수가 열거형의 첫 번째 요소를 검색합니다. 그런 다음 dwFlags 매개 변수에서 CRYPT_NEXT 플래그를 설정하여 후속 요소를 검색할 수 있습니다. ERROR_NO_MORE_ITEMS 오류 코드로 인해 이 함수가 실패하면 열거형의 끝에 도달했습니다. 이 함수는 스레드로부터 안전하지 않으며 이 함수가 다중 스레드 컨텍스트에서 사용되는 경우 사용 가능한 모든 알고리즘이 열거되지 않을 수 있습니다. |
|
쿼리 중인 CSP에서 지원하는 하나의 알고리즘에 대한 정보를 포함하는 PROV_ENUMALGS_EX 구조체입니다. 반환된 구조체에는 PP_ENUMALGS 대해 반환된 구조체보다 알고리즘에 대한 자세한 정보가 포함되어 있습니다.
이 값을 처음 읽을 때 dwFlags 매개 변수에는 CRYPT_FIRST 플래그가 포함되어야 합니다. 이렇게 하면 이 함수가 열거형의 첫 번째 요소를 검색합니다. 그런 다음 dwFlags 매개 변수에서 CRYPT_NEXT 플래그를 설정하여 후속 요소를 검색할 수 있습니다. ERROR_NO_MORE_ITEMS 오류 코드로 인해 이 함수가 실패하면 열거형의 끝에 도달했습니다. 이 함수는 스레드로부터 안전하지 않으며 이 함수가 다중 스레드 컨텍스트에서 사용되는 경우 사용 가능한 모든 알고리즘이 열거되지 않을 수 있습니다. |
|
CSP에서 null로 종료된 CHAR 문자열 형식으로 유지 관리하는 키 컨테이너 중 하나의 이름입니다.
이 값을 처음 읽을 때 dwFlags 매개 변수에는 CRYPT_FIRST 플래그가 포함되어야 합니다. 이렇게 하면 이 함수가 열거형의 첫 번째 요소를 검색합니다. 그런 다음 dwFlags 매개 변수에서 CRYPT_NEXT 플래그를 설정하여 후속 요소를 검색할 수 있습니다. ERROR_NO_MORE_ITEMS 오류 코드로 인해 이 함수가 실패하면 열거형의 끝에 도달했습니다. 컴퓨터와 연결된 키 컨테이너를 열거하려면 먼저 CRYPT_MACHINE_KEYSET 플래그를 사용하여 CryptAcquireContext를 호출한 다음 CryptAcquireContext에서 반환된 핸들을 CryptGetProvParam 호출에서 hProv 매개 변수로 사용합니다. 이 함수는 스레드로부터 안전하지 않으며 이 함수가 다중 스레드 컨텍스트에서 사용되는 경우 사용 가능한 모든 알고리즘이 열거되지 않을 수 있습니다. |
|
이 상수는 사용되지 않습니다. |
|
현재 CSP가 PROV_ENUMALGS_EX 구조체의 dwProtocols 멤버를 지원한다는 것을 나타냅니다. 이 함수가 성공하면 CSP는 PROV_ENUMALGS_EX 구조체의 dwProtocols 멤버를 지원합니다. 이 함수가 NTE_BAD_TYPE 오류 코드와 함께 실패하면 CSP는 dwProtocols 멤버를 지원하지 않습니다. |
|
이 상수는 사용되지 않습니다. |
|
CSP가 구현되는 방법을 나타내는 DWORD 값입니다. 가능한 값의 표는 비고를 참조하세요. |
|
이 쿼리는 사용되지 않습니다. |
|
키 교환 PIN이 pbData에 포함되도록 지정합니다. PIN은 null로 끝나는 ASCII 문자열로 표시됩니다. |
|
키 스토리지 컨테이너에 대한 보안 설명자를 검색합니다. pbData 매개 변수는 키 스토리지 컨테이너에 대한 보안 설명자를 수신하는 SECURITY_DESCRIPTOR 구조체의 주소입니다. 보안 설명자는 자체 상대 형식으로 반환됩니다. |
|
hProv 매개 변수가 컴퓨터 키 집합인지 여부를 확인합니다. pbData 매개 변수는 DWORD여야 합니다. 해당 플래그가 CryptAcquireContext 함수에 전달된 경우 DWORD가 CRYPT_MACHINE_KEYSET 플래그로 설정됩니다. |
|
CSP에서 지원하는 키 지정자 값에 대한 정보를 반환합니다. 키 지정자 값은 논리 OR 에 조인되고 호출의 pbData 매개 변수에 DWORD로 반환됩니다. 예를 들어 Microsoft 기본 암호화 공급자 버전 1.0은 DWORD 값 AT_SIGNATURE | AT_KEYEXCHANGE. |
|
CRYPT_SEC_DESCR DWORD 값을 반환합니다. |
|
AT_KEYEXCHANGE 증분 길이의 비트 수입니다. 이 정보는 PP_ENUMALGS_EX 값에 반환된 정보와 함께 사용됩니다. PP_ENUMALGS_EX 및 PP_KEYX_KEYSIZE_INC 사용할 때 반환되는 정보를 사용하여 AT_KEYEXCHANGE 유효한 키 길이를 확인할 수 있습니다. 그런 다음 이러한 키 길이를 CryptGenKey와 함께 사용할 수 있습니다. 예를 들어 CSP가 최소 키 길이가 512비트이고 최대 1024비트인 CALG_RSA_KEYX(AT_KEYEXCHANGE)를 열거하고 증분 길이를 64비트로 반환하는 경우 유효한 키 길이는 512, 576, 640입니다,... 1024. |
|
Null로 끝나는 CHAR 문자열 형식의 CSP 이름입니다. 이 문자열은 현재 CSP를 사용하도록 지정하기 위해 CryptAcquireContext 함수의 pszProvider 매개 변수에 전달된 문자열과 동일합니다. |
|
CSP의 공급자 유형을 나타내는 DWORD 값입니다. |
|
스마트 카드 대한 루트 인증서 저장소를 가져옵니다. 이 인증서 저장소에는 스마트 카드 저장된 모든 루트 인증서가 포함되어 있습니다.
pbData 매개 변수는 인증서 저장소의 핸들을 수신하는 HCERTSTORE 변수의 주소입니다. 이 핸들이 더 이상 필요하지 않으면 호출자는 CertCloseStore 함수를 사용하여 핸들을 닫아야 합니다. Windows Server 2003 및 Windows XP: 이 매개 변수는 지원되지 않습니다. |
|
세션 키의 크기(비트)입니다. |
|
서버 제어 암호화와 함께 사용됩니다. |
|
AT_SIGNATURE 증분 길이의 비트 수입니다. 이 정보는 PP_ENUMALGS_EX 값에 반환된 정보와 함께 사용됩니다. PP_ENUMALGS_EX 및 PP_SIG_KEYSIZE_INC 사용할 때 반환되는 정보를 사용하여 AT_SIGNATURE 유효한 키 길이를 확인할 수 있습니다. 그런 다음 이러한 키 길이를 CryptGenKey와 함께 사용할 수 있습니다.
예를 들어 CSP가 최소 키 길이가 512비트이고 최대 1024비트인 CALG_RSA_SIGN(AT_SIGNATURE)를 열거하고 증분 길이를 64비트로 반환하는 경우 유효한 키 길이는 512, 576, 640입니다,... 1024. |
|
키 서명 PIN이 pbData에 포함되도록 지정합니다. PIN은 null로 끝나는 ASCII 문자열로 표시됩니다. |
|
스마트 카드 식별자를 가져옵니다. pbData 매개 변수는 스마트 카드 식별자를 수신하는 GUID 구조체의 주소입니다.
Windows Server 2003 및 Windows XP: 이 매개 변수는 지원되지 않습니다. |
|
스마트 카드 판독기의 이름을 가져옵니다. pbData 매개 변수는 스마트 카드 판독기의 이름을 포함하는 null로 종료된 ANSI 문자열을 수신하는 ANSI 문자 배열의 주소입니다. pdwDataLen 매개 변수가 가리키는 변수에 포함된 이 버퍼의 크기에는 NULL 종결자가 포함되어야 합니다.
Windows Server 2003 및 Windows XP: 이 매개 변수는 지원되지 않습니다. |
|
대칭 키의 크기입니다. |
|
이 쿼리는 사용되지 않습니다. |
|
null로 끝나는 CHAR 문자열 형식의 현재 키 컨테이너의 고유 컨테이너 이름입니다. 많은 CSP의 경우 이 이름은 PP_CONTAINER 값을 사용할 때 반환되는 이름과 같습니다. CryptAcquireContext 함수는 이 컨테이너 이름으로 작동해야 합니다. |
|
하드웨어 RNG(난수 생성기)가 지원되는지 여부를 나타냅니다. PP_USE_HARDWARE_RNG 지정하면 함수가 성공하고 하드웨어 RNG가 지원되는 경우 TRUE를 반환합니다. 하드웨어 RNG가 지원되지 않으면 함수가 실패하고 FALSE 를 반환합니다. RNG가 지원되는 경우 CSP 가 이 공급자 컨텍스트에 하드웨어 RNG를 단독으로 사용해야 함을 나타내기 위해 CryptSetProvParam 에서 PP_USE_HARDWARE_RNG 설정할 수 있습니다. PP_USE_HARDWARE_RNG 사용하는 경우 pbData 매개 변수는 NULL이어야 하고 dwFlags는 0이어야 합니다.
현재 하드웨어 RNG 사용을 지원하는 Microsoft CSP는 없습니다. |
|
스마트 카드 대한 사용자 인증서 저장소를 가져옵니다. 이 인증서 저장소에는 스마트 카드 저장된 모든 사용자 인증서가 포함되어 있습니다. 이 저장소의 인증서는 PKCS_7_ASN_ENCODING 또는 X509_ASN_ENCODING 인코딩을 사용하여 인코딩되며 CERT_KEY_PROV_INFO_PROP_ID 속성을 포함해야 합니다.
pbData 매개 변수는 메모리 내 인증서 저장소의 핸들을 수신하는 HCERTSTORE 변수의 주소입니다. 이 핸들이 더 이상 필요하지 않으면 호출자는 CertCloseStore 함수를 사용하여 핸들을 닫아야 합니다. Windows Server 2003 및 Windows XP: 이 매개 변수는 지원되지 않습니다. |
|
CSP의 버전 번호입니다. 가장 중요하지 않은 바이트에는 부 버전 번호와 주 버전 번호의 다음으로 가장 중요한 바이트가 포함됩니다. 버전 2.0은 0x00000200 표시됩니다. 이전 버전의 Microsoft 기본 암호화 공급자 및 Microsoft 고급 암호화 공급자와의 이전 버전과의 호환성을 유지하기 위해 공급자 이름은 이후 버전에서 "v1.0" 지정을 유지합니다. |
[out] pbData
데이터를 수신할 버퍼에 대한 포인터입니다. 이 데이터의 형식은 dwParam 값에 따라 달라집니다. dwParam이 PP_USE_HARDWARE_RNG 설정되면 pbData를 NULL로 설정해야 합니다.
이 매개 변수는 메모리 할당을 위해 이 정보의 크기를 설정하는 NULL 일 수 있습니다. 자세한 내용은 알 수 없는 길이의 데이터 검색을 참조하세요.
[in, out] pdwDataLen
pbData 매개 변수가 가리키는 버퍼의 크기(바이트)를 지정하는 DWORD 값에 대한 포인터입니다. 함수가 반환될 때 DWORD 값에는 버퍼에 저장되거나 저장될 바이트 수가 포함됩니다.
PP_ENUMALGS 또는 PP_ENUMALGS_EX 설정된 경우 pdwDataLen 매개 변수는 약간 다르게 작동합니다. pbData가 NULL이거나 pdwDataLen이 가리키는 값이 너무 작으면 이 매개 변수에서 반환되는 값은 현재 읽는 항목의 크기가 아니라 열거형 목록에서 가장 큰 항목의 크기입니다.
PP_ENUMCONTAINERS 설정되면 함수에 대한 첫 번째 호출은 현재 공급자가 허용하는 최대 키 컨테이너의 크기를 반환합니다. 이는 가장 긴 기존 컨테이너의 길이 또는 현재 컨테이너의 길이를 반환하는 것과 같은 다른 가능한 동작과는 대조적입니다. 후속 열거 호출은 dwLen 매개 변수를 변경하지 않습니다. 열거된 각 컨테이너에 대해 호출자는 원하는 경우 프로그래밍 방식으로 null로 끝나는 문자열의 길이를 확인할 수 있습니다. 열거형 값 중 하나를 읽고 pbData 매개 변수가 NULL인 경우 크기 정보를 올바르게 검색하려면 CRYPT_FIRST 플래그를 지정해야 합니다.
[in] dwFlags
dwParam이 PP_KEYSET_SEC_DESCR 경우 키가 저장된 키 컨테이너의 보안 설명자가 검색됩니다. 이 경우 dwFlags 는 플랫폼 SDK에 정의된 대로 요청된 보안 정보를 나타내는 SECURITY_INFORMATION 비트 플래그를 전달하는 데 사용됩니다. SECURITY_INFORMATION 비트 플래그를 비트 OR 연산과 결합할 수 있습니다.
다음 값은 PP_KEYSET_SEC_DESCR 사용하기 위해 정의됩니다.
다음 값은 PP_ENUMALGS, PP_ENUMALGS_EX 및 PP_ENUMCONTAINERS 사용하기 위해 정의됩니다.
| 값 | 의미 |
|---|---|
|
열거형의 첫 번째 요소를 검색합니다. 이는 열거자를 다시 설정하는 것과 동일한 효과가 있습니다. |
|
열거형에서 다음 요소를 검색합니다. 검색할 요소가 더 이상 없으면 이 함수는 실패하고 마지막 오류를 ERROR_NO_MORE_ITEMS 설정합니다. |
|
SGC( 서버 제어 암호화 )가 설정된 인증서를 검색합니다. SGC 사용 인증서는 더 이상 지원되지 않습니다. |
|
이 플래그는 사용되지 않습니다. |
|
이 플래그는 사용되지 않습니다. |
반환 값
함수가 성공하면 반환 값은 0이 아닌 값(TRUE)입니다.
함수가 실패하면 반환 값은 0(FALSE)입니다. 확장 오류 정보는 GetLastError를 호출합니다.
NTE가 앞에 있는 오류 코드는 사용 중인 특정 CSP에 의해 생성됩니다. 몇 가지 가능한 오류 코드는 다음과 같습니다.
| 반환 코드 | 설명 |
|---|---|
|
매개 변수 중 하나는 유효하지 않은 핸들을 지정합니다. |
|
매개 변수 중 하나에 유효하지 않은 값이 포함되어 있습니다. 이는 가장 자주 유효하지 않은 포인터입니다. |
|
pbData 매개 변수로 지정된 버퍼가 반환된 데이터를 저장할 만큼 크지 않은 경우 함수는 ERROR_MORE_DATA 코드를 설정하고 pdwDataLen이 가리키는 변수에 필요한 버퍼 크기를 바이트 단위로 저장합니다. |
|
열거형 목록의 끝에 도달했습니다. pbData 버퍼에 유효한 데이터가 배치되지 않았습니다. 이 오류 코드는 dwParam 이 PP_ENUMALGS 또는 PP_ENUMCONTAINERS 경우에만 반환됩니다. |
|
dwFlags 매개 변수는 유효하지 않은 플래그를 지정합니다. |
|
dwParam 매개 변수는 알 수 없는 값 번호를 지정합니다. |
|
hProv에서 지정한 CSP 컨텍스트가 잘못되었습니다. |
설명
이 함수는 다중 스레드 프로그램의 스레드에서 사용하면 안 됩니다.
dwParam이 PP_IMPTYPE 경우 다음 값이 pbData에 반환됩니다.
| 값 | 의미 |
|---|---|
| CRYPT_IMPL_HARDWARE 0x01 |
구현은 하드웨어에 있습니다. |
| CRYPT_IMPL_SOFTWARE 0x02 |
구현은 소프트웨어에 있습니다. |
| CRYPT_IMPL_MIXED 0x03 |
구현에는 하드웨어와 소프트웨어가 모두 포함됩니다. |
| CRYPT_IMPL_UNKNOWN 0x04 |
구현 유형을 알 수 없습니다. |
| CRYPT_IMPL_REMOVABLE 0x08 |
구현은 이동식 미디어에 있습니다. |
dwFlags 매개 변수는 요청된 보안 정보를 나타내는 SECURITY_INFORMATION 비트 플래그를 전달하는 데 사용됩니다. 보안 설명자에 대한 포인터는 pbData 매개 변수에 반환되고 보안 설명자의 길이는 pdwDataLen 매개 변수에 반환됩니다. 키 컨테이너 보안은 SetFileSecurity 및 GetFileSecurity를 사용하여 처리됩니다.
PP_ENUMALGS 또는 PP_ENUMALGS_EX 설정된 dwParam 으로 열거된 알고리즘의 클래스를 확인할 수 있습니다. 지원되는 암호화 알고리즘 목록을 표시하고 나머지를 무시하기 위해 이 작업을 수행할 수 있습니다. GET_ALG_CLASS(x) 매크로는 알고리즘 식별자를 인수로 사용하고 해당 알고리즘의 일반 클래스를 나타내는 코드를 반환합니다. 가능한 반환 값은 다음과 같습니다.
- ALG_CLASS_DATA_ENCRYPT
- ALG_CLASS_HASH
- ALG_CLASS_KEY_EXCHANGE
- ALG_CLASS_SIGNATURE
다음 표에서는 각 알고리즘의 클래스와 함께 Microsoft 기본 암호화 공급자에서 지원하는 알고리즘을 나열합니다.
| Name | ID | 클래스 |
|---|---|---|
| "MD2" | CALG_MD2 | ALG_CLASS_HASH |
| "MD5" | CALG_MD5 | ALG_CLASS_HASH |
| "SHA" | CALG_SHA | ALG_CLASS_HASH |
| "MAC" | CALG_MAC | ALG_CLASS_HASH |
| "RSA_SIGN" | CALG_RSA_SIGN | ALG_CLASS_SIGNATURE |
| "RSA_KEYX" | CALG_RSA_KEYX | ALG_CLASS_KEY_EXCHANGE |
| "RC2" | CALG_RC2 | ALG_CLASS_DATA_ENCRYPT |
| "RC4" | CALG_RC4 | ALG_CLASS_DATA_ENCRYPT |
애플리케이션은 인식되지 않는 알고리즘 식별자와 함께 알고리즘을 사용하면 안 됩니다. 알 수 없는 암호화 알고리즘을 사용하면 예측할 수 없는 결과를 생성할 수 있습니다.
예제
다음 예제에서는 암호화 서비스 공급자 핸들과 연결된 CSP의 이름과 핸들과 연결된 키 컨테이너의 이름을 찾는 방법을 보여 줍니다. 이 예제의 전체 컨텍스트는 예제 C 프로그램: CryptAcquireContext 사용을 참조하세요.
이 함수를 사용하는 또 다른 예제는 예제 C 프로그램: CSP 공급자 및 공급자 형식 열거를 참조하세요.
//-----------------------------------------------------------------
// Declare and initialize variables.
HCRYPTPROV hCryptProv;
BYTE pbData[1000]; // 1000 will hold the longest
// key container name.
DWORD cbData;
//-------------------------------------------------------------------
// An HCRYPTPROV must be acquired before using code like that in
// "Example C Program Using CryptAcquireContext."
//-------------------------------------------------------------------
// Read the name of the default CSP.
cbData = 1000;
if(CryptGetProvParam(
hCryptProv,
PP_NAME,
pbData,
&cbData,
0))
{
printf("CryptGetProvParam succeeded.\n");
printf("Provider name: %s\n", pbData);
}
else
{
printf("Error reading CSP name. \n");
exit(1);
}
//--------------------------------------------------------------------
// Read the name of the default key container.
cbData = 1000;
if(CryptGetProvParam(
hCryptProv,
PP_CONTAINER,
pbData,
&cbData,
0))
{
printf("CryptGetProvParam succeeded. \n");
printf("Key Container name: %s\n", pbData);
}
else
{
printf("Error reading key container name. \n");
exit(1);
}
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | wincrypt.h |
| 라이브러리 | Advapi32.lib |
| DLL | Advapi32.dll |