CryptSetKeyParam 함수(wincrypt.h)
Microsoft 기본 암호화 공급자는 키 교환 또는 서명 키에 대한 설정 값을 허용하지 않습니다. 그러나 사용자 지정 공급자는 키에 대해 설정할 수 있는 값을 정의할 수 있습니다.
구문
BOOL CryptSetKeyParam(
[in] HCRYPTKEY hKey,
[in] DWORD dwParam,
[in] const BYTE *pbData,
[in] DWORD dwFlags
);
매개 변수
[in] hKey
값을 설정할 키에 대한 핸들입니다.
[in] dwParam
다음 표에는 사용할 수 있는 미리 정의된 값이 포함되어 있습니다.
모든 키 형식에 대해 이 매개 변수는 다음 값 중 하나를 포함할 수 있습니다.
| 값 | 의미 |
|---|---|
|
pbData 는 적절한 ALG_ID 가리킵니다. 세션 키를 Microsoft 기본 DSS(디지털 서명 표준), Diffie-Hellman 암호화 공급자 또는 호환되는 CSP와 교환할 때 사용됩니다. Key가 CryptImportKey 함수와 합의되면 알고리즘 유형을 설정하여 세션 키를 사용할 수 있습니다. |
|
pbData는 DER(Distinguished Encoding Rules)를 사용하여 인코딩된 X.509 인증서를 포함하는 버퍼의 주소입니다. 인증서의 공개 키는 해당 서명 또는 교환 키와 일치해야 합니다. |
|
pbData 는 0개 이상의 권한 플래그를 지정하는 DWORD 값을 가리킵니다. 이러한 플래그에 대한 설명은 CryptGetKeyParam을 참조하세요. |
|
pbData는 세션 키의 일부로 만들 새 솔트 값을 지정하는 BYTE 배열을 가리킵니다. 솔트 값의 크기는 사용 중인 CSP에 따라 달라집니다. 이 값을 설정하기 전에 CryptGetKeyParam 함수를 호출하여 솔트 값의 크기를 결정합니다. 솔트 값은 세션 키를 보다 고유하게 만드는 데 사용되어 사전 공격을 더 어렵게 만듭니다. Microsoft 기본 암호화 공급자에 대한 솔트 값은 기본적으로 0입니다. |
|
pbData 는 솔트가 포함된 CRYPT_INTEGER_BLOB 구조를 가리킵니다. 자세한 내용은 솔트 값 지정을 참조하세요. |
hKey 매개 변수로 DSS(디지털 서명 표준) 키를 지정하는 경우 dwParam 값을 다음 값 중 하나로 설정할 수도 있습니다.
| 값 | 의미 |
|---|---|
|
pbData 는 DSS 키 BLOB에서 생성기 G를 가리킵니다. 데이터는 pbData 멤버가 값이고 cbData 멤버가 값의 길이인 CRYPT_INTEGER_BLOB 구조체 형식입니다. 값은 헤더 정보가 없고 little-endian 형식으로 필요합니다. |
|
pbData 는 DSS 키 BLOB의 주요 모듈러스 P를 가리킵니다. 데이터는 CRYPT_INTEGER_BLOB 구조체 형식입니다. pbData 멤버는 값이고 cbData 멤버는 값의 길이입니다. 값은 헤더 정보가 없고 little-endian 형식으로 필요합니다. |
|
pbData 는 DSS 키 BLOB의 주요 Q를 가리킵니다. 데이터는 pbData 멤버가 값이고 cbData 멤버가 값의 길이인 CRYPT_INTEGER_BLOB 구조체 형식입니다. 값은 헤더 정보가 없고 little-endian 형식으로 필요합니다. |
|
P, Q 및 G 값이 설정되면 pbData 매개 변수에 대한 dwParam 및 NULL에 대한 KP_X 값을 지정하는 호출을 CryptSetKeyParam 함수에 수행할 수 있습니다. 이렇게 하면 X 및 Y 값이 생성됩니다. |
diffie-Hellman 알고리즘 또는 DSA(디지털 서명 알고리즘) 키가 hKey로 지정된 경우 dwParam 값을 다음 값 중 하나로 설정할 수도 있습니다.
| 값 | 의미 |
|---|---|
|
가져온 Diffie-Hellman 키에 대한 정보를 설정합니다. pbData 매개 변수는 설정할 키 정보를 포함하는 CMS_DH_KEY_INFO 구조체의 주소입니다. |
|
DSS 또는 Diffie-Hellman 키의 공용 매개 변수(P, Q, G 등)를 설정합니다. 이 키의 키 핸들은 preGEN 상태여야 하며 CRYPT_PREGEN 플래그와 함께 생성됩니다. pbData 매개 변수는 이 구조체의 데이터가 DHPUBKEY_VER3 또는 DSSPUBKEY_VER3 BLOB인 DATA_BLOB 구조체에 대한 포인터여야 합니다. 함수는 이 CRYPT_INTEGER_BLOB 구조체의 공용 매개 변수를 키 핸들로 복사합니다. 이 호출이 수행되면 KP_X 매개 변수 값을 CryptSetKeyParam 과 함께 사용하여 실제 프라이빗 키를 만들어야 합니다. KP_PUB_PARAMS 매개 변수는 매개 변수 값이 KP_P, KP_Q 및 KP_G 여러 호출이 아닌 하나의 호출로 사용됩니다. |
hKey 매개 변수로 블록 암호세션 키를 지정하는 경우 dwParam 값을 다음 값 중 하나로 설정할 수도 있습니다.
| 값 | 의미 |
|---|---|
|
이 값 형식은 RC2 키에서만 사용할 수 있으며 Windows 2000 이전 Microsoft 고급 암호화 공급자에서 CryptSetKeyParam 함수를 구현하여 추가되었습니다. 이전 구현에서 고급 공급자의 RC2 키는 강도가 128비트였지만 키를 키 테이블로 확장하는 데 사용된 유효 키 길이는 40비트였습니다. 이렇게 하면 알고리즘의 강도가 40비트로 감소했습니다. 이전 버전과의 호환성을 유지하기 위해 이전 구현은 그대로 유지됩니다. 그러나 CryptSetKeyParam 호출에서 KP_EFFECTIVE_KEYLEN 사용하여 유효 키 길이를 40비트 이상으로 설정할 수 있습니다. 유효 키 길이는 유효 키 길이 값이 있는 DWORD 값에 대한 포인터로 pbData 매개 변수에 전달됩니다. Microsoft 기본 암호화 공급자의 최소 유효 키 길이는 1이고 최대 키 길이는 40입니다. Microsoft 고급 암호화 공급자에서 최소값은 1이고 최대값은 1,024입니다. 키로 암호화하거나 암호를 해독하기 전에 키 길이를 설정해야 합니다. |
|
허용되는 가장 높은 TLS( 전송 계층 보안 ) 버전을 설정합니다. 이 속성은 SSL 및 TLS 키에만 적용됩니다. pbData 매개 변수는 지원되는 가장 높은 TLS 버전 번호를 포함하는 DWORD 변수의 주소입니다. |
|
pbData 는 초기화 벡터를 지정하는 BYTE 배열을 가리킵니다. 이 배열에는 BlockLength/8 요소가 포함되어야 합니다. 예를 들어 블록 길이가 64비트인 경우 초기화 벡터는 8바이트로 구성됩니다.
초기화 벡터는 Microsoft 기본 암호화 공급자에 대해 기본적으로 0으로 설정됩니다. |
|
DES( 데이터 암호화 표준 ) 키의 키 값을 설정합니다. pbData 매개 변수는 키가 포함된 버퍼의 주소입니다. 이 버퍼는 키와 길이가 같아야 합니다. 이 속성은 DES 키에만 적용됩니다. |
|
패딩 모드를 설정합니다. pbData 매개 변수는 암호에서 사용하는 안쪽 여백 메서드를 식별하는 숫자 식별자를 수신하는 DWORD 값에 대한 포인터입니다. 다음 값 중 하나일 수 있습니다. |
|
pbData는 사용할 암호 모드를 지정하는 DWORD 값을 가리킵니다. 정의된 암호 모드 목록은 CryptGetKeyParam을 참조하세요. 암호화 모드는 Microsoft 기본 암호화 공급자에 대해 기본적으로 CRYPT_MODE_CBC 설정됩니다. |
|
pbData는 OFB(출력 피드백) 또는 CFB(암호 피드백) 암호화 모드를 사용할 때 주기당 처리되는 비트 수를 나타내는 DWORD 값을 가리킵니다. 주기당 처리되는 비트 수는 Microsoft 기본 암호화 공급자에 대해 기본적으로 8로 설정됩니다. |
rSA 키가 hKey 매개 변수에 지정된 경우 dwParam 매개 변수 값은 다음 값일 수 있습니다.
| 값 | 의미 |
|---|---|
|
키에 대한 OAEP(최적 비대칭 암호화 패딩)(PKCS #1 버전 2) 매개 변수를 설정합니다. pbData 매개 변수는 OAEP 레이블을 포함하는 CRYPT_DATA_BLOB 구조체의 주소입니다. 이 속성은 RSA 키에만 적용됩니다. |
다음 값은 사용되지 않습니다.
- KP_ADMIN_PIN
- KP_CMS_KEY_INFO
- KP_INFO
- KP_KEYEXCHANGE_PIN
- KP_PRECOMP_MD5
- KP_PRECOMP_SHA
- KP_PREHASH
- KP_PUB_EX_LEN
- KP_PUB_EX_VAL
- KP_RA
- KP_RB
- KP_ROUNDS
- KP_RP
- KP_SIGNATURE_PIN
- KP_Y
[in] pbData
CryptSetKeyParam을 호출하기 전에 설정할 값으로 초기화된 버퍼에 대한 포인터입니다. 이 데이터의 형식은 dwParam 값에 따라 달라집니다.
[in] dwFlags
dwParam이 KP_ALGID 경우에만 사용됩니다. dwFlags 매개 변수는 활성화된 키에 대한 플래그 값을 전달하는 데 사용됩니다. dwFlags 매개 변수는 CryptGenKey를 사용하여 동일한 유형의 키를 생성할 때 허용되는 키 크기 및 다른 플래그 값과 같은 값을 보유할 수 있습니다. 허용되는 플래그 값에 대한 자세한 내용은 CryptGenKey를 참조하세요.
반환 값
함수가 성공하면 반환 값은 0이 아닌 값(TRUE)입니다.
함수가 실패하면 반환 값은 0(FALSE)입니다. 확장 오류 정보는 GetLastError를 호출합니다.
"NTE"가 앞에 있는 오류 코드는 사용 중인 특정 CSP에 의해 생성됩니다. 몇 가지 가능한 오류 코드는 다음과 같습니다.
| 반환 코드 | 설명 |
|---|---|
|
CSP 컨텍스트는 현재 다른 프로세스에서 사용되고 있습니다. |
|
매개 변수 중 하나는 유효하지 않은 핸들을 지정합니다. |
|
매개 변수 중 하나에 유효하지 않은 값이 포함되어 있습니다. 이는 가장 자주 유효하지 않은 포인터입니다. |
|
dwFlags 매개 변수가 0이 아니거나 pbData 버퍼에 유효하지 않은 값이 포함되어 있습니다. |
|
dwParam 매개 변수는 알 수 없는 매개 변수를 지정합니다. |
|
hKey 키를 만들 때 지정된 CSP 컨텍스트를 찾을 수 없습니다. |
|
함수가 예기치 않은 방식으로 실패했습니다. |
|
일부 CSP에는 하드 코딩된 P, Q 및 G 값이 있습니다. 이 경우 dwParam 값에 KP_P, KP_Q 및 KP_G 사용하면 이 오류가 발생합니다. |
설명
KP_Q, KP_P 또는 KP_X 매개 변수가 PREGEN Diffie-Hellman 또는 DSS 키에 설정된 경우 키 길이는 CryptGenKey를 사용하여 키를 만들 때 dwFlags 매개 변수의 상위 16비트 를 사용하여 설정된 키 길이와 호환되어야 합니다. CryptGenKey에 키 길이가 설정되지 않은 경우 기본 키 길이가 사용되었습니다. 이렇게 하면 기본이 아닌 키 길이를 사용하여 P, Q 또는 X를 설정하는 경우 오류가 발생합니다.
예제
이 함수를 사용하는 예제는 예제 C 프로그램: 세션 키 복제를 참조하세요. 이 함수를 사용하는 더 많은 코드는 예제 C 프로그램: 세션 키 매개 변수 설정 및 가져오기를 참조하세요 .
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | wincrypt.h |
| 라이브러리 | Advapi32.lib |
| DLL | Advapi32.dll |
추가 정보
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기