다음을 통해 공유


CryptSetKeyParam 함수(wincrypt.h)

중요 이 API는 더 이상 사용되지 않습니다. 신규 및 기존 소프트웨어는 암호화 차세대 API를 사용하기 시작해야 합니다. Microsoft는 이후 릴리스에서 이 API를 제거할 수 있습니다.
 
CryptSetKeyParam 함수는 세션 키 작업의 다양한 측면을 사용자 지정합니다. 이 함수에서 설정한 값은 메모리에 유지되지 않으며 단일 세션에서만 사용할 수 있습니다.

Microsoft 기본 암호화 공급자 키 교환 또는 서명 키에 대한 설정 값을 허용하지 않습니다. 그러나 사용자 지정 공급자는 해당 키에 대해 설정할 수 있는 값을 정의할 수 있습니다.

통사론

BOOL CryptSetKeyParam(
  [in] HCRYPTKEY  hKey,
  [in] DWORD      dwParam,
  [in] const BYTE *pbData,
  [in] DWORD      dwFlags
);

매개 변수

[in] hKey

값을 설정할 키에 대한 핸들입니다.

[in] dwParam

다음 표에는 사용할 수 있는 미리 정의된 값이 포함되어 있습니다.

모든 키 형식에 대해 이 매개 변수는 다음 값 중 하나를 포함할 수 있습니다.

의미
KP_ALGID
pbData 적절한 ALG_ID가리킵니다. 세션 키를 Microsoft 기본 DSS(디지털 서명 표준), Diffie-Hellman 암호화 공급자 또는 호환되는 CSP와 교환할 때 사용됩니다. key가 CryptImportKey 함수와 합의된 후에는 알고리즘 유형을 설정하여 세션 키를 사용할 수 있습니다.
KP_CERTIFICATE
pbData DER(고유 인코딩 규칙)를 사용하여 인코딩된 X.509 인증서를 포함하는 버퍼의 주소입니다. 인증서의 공개 키는 해당 서명 또는 교환 키와 일치해야 합니다.
KP_PERMISSIONS
pbData 0개 이상의 사용 권한 플래그를 지정하는 DWORD 값을 가리킵니다. 이러한 플래그에 대한 설명은 CryptGetKeyParam참조하세요.
KP_SALT
pbData 세션 키의 일부로 만들 새 솔트 값을 지정하는 BYTE 배열을 가리킵니다. 솔트 값의 크기는 사용 중인 CSP에 따라 달라집니다. 이 값을 설정하기 전에 CryptGetKeyParam 함수를 호출하여 솔트 값의 크기를 결정합니다. 솔트 값은 세션 키를 더 고유하게 만드는 데 사용되어 사전 공격을 더 어렵게 만듭니다. Microsoft Base 암호화 공급자의 경우 솔트 값은 기본적으로 0입니다.
KP_SALT_EX
pbData 솔트를 포함하는 CRYPT_INTEGER_BLOB 구조를 가리킵니다. 자세한 내용은 솔트 값지정을 참조하세요.
 

DSS(Digital Signature Standard) 키가 hKey 매개 변수에 의해 지정된 경우 dwParam 값도 다음 값 중 하나로 설정할 수 있습니다.

의미
KP_G
pbData DSS 키 BLOB생성기 G를 가리킵니다. 데이터는 CRYPT_INTEGER_BLOB 구조체의 형태로, 여기서 pbData 멤버는 값이고 cbData 멤버는 값의 길이입니다. 이 값은 헤더 정보가 없고 little-endian 형식으로 필요합니다.
KP_P
pbData DSS 키 BLOB의 주요 모듈러스 P를 가리킵니다. 데이터는 CRYPT_INTEGER_BLOB 구조체 형식입니다. pbData 멤버는 값이고 cbData 멤버는 값의 길이입니다. 이 값은 헤더 정보가 없고 little-endian 형식으로 필요합니다.
KP_Q
pbData DSS 키 BLOB의 주요 Q를 가리킵니다. 데이터는 pbData 멤버가 값이고 cbData 멤버가 값의 길이인 CRYPT_INTEGER_BLOB 구조체 형식입니다. 이 값은 헤더 정보가 없고 little-endian 형식으로 필요합니다.
KP_X
P, Q 및 G 값이 설정되면 dwParam KP_X 값을 지정하고 pbData 매개 변수에 대한 NULLCryptSetKeyParam 함수에 대해 호출할 수 있습니다. 이로 인해 X 및 Y 값이 생성됩니다.
 

Diffie-Hellman 알고리즘 또는 DSA(디지털 서명 알고리즘) 키가 hKey지정된 경우 dwParam 값도 다음 값 중 하나로 설정할 수 있습니다.

의미
KP_CMS_DH_KEY_INFO
가져온 Diffie-Hellman 키에 대한 정보를 설정합니다. pbData 매개 변수는 설정할 키 정보를 포함하는 CMS_DH_KEY_INFO 구조체의 주소입니다.
KP_PUB_PARAMS
DSS 또는 Diffie-Hellman 키의 공용 매개 변수(P, Q, G 등)를 설정합니다. 이 키의 키 핸들은 CRYPT_PREGEN 플래그를 사용하여 생성된 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 값도 다음 값 중 하나로 설정할 수 있습니다.

의미
KP_EFFECTIVE_KEYLEN
이 값 형식은 RC2 키에서만 사용할 수 있으며 Windows 2000 이전의 Microsoft 고급 암호화 공급자에서 CryptSetKeyParam 함수의 구현으로 인해 추가되었습니다. 이전 구현에서 고급 공급자의 RC2 키는 강도가 128비트였지만 키를 키 테이블로 확장하는 데 사용된 유효 키 길이는 40비트였습니다. 이렇게 하면 알고리즘의 강도가 40비트로 감소했습니다. 이전 버전과의 호환성을 유지하기 위해 이전 구현은 그대로 유지됩니다. 그러나 CryptSetKeyParam 호출에서 KP_EFFECTIVE_KEYLEN 사용하여 유효 키 길이를 40비트 이상으로 설정할 수 있습니다. 유효 키 길이는 유효 키 길이 값이 있는 DWORD 값에 대한 포인터로 pbData 매개 변수에 전달됩니다. Microsoft 기본 암호화 공급자의 최소 유효 키 길이는 1이고 최대 키 길이는 40입니다. Microsoft 고급 암호화 공급자에서 최소값은 1이고 최대값은 1,024입니다. 키로 암호화하거나 암호를 해독하기 전에 키 길이를 설정해야 합니다.
KP_HIGHEST_VERSION
허용되는 가장 높은 TLS(전송 계층 보안) 버전을 설정합니다. 이 속성은 SSL 및 TLS 키에만 적용됩니다. pbData 매개 변수는 지원되는 가장 높은 TLS 버전 번호를 포함하는 DWORD 변수의 주소입니다.
KP_IV
pbData 초기화 벡터를 지정하는 BYTE 배열을 가리킵니다. 이 배열에는 BlockLength/8 요소가 포함되어야 합니다. 예를 들어 블록 길이가 64비트인 경우 초기화 벡터는 8바이트로 구성됩니다.

초기화 벡터는 Microsoft 기본 암호화 공급자에 대해 기본적으로 0으로 설정됩니다.

KP_KEYVAL
DES(데이터 암호화 표준) 키의 키 값을 설정합니다. pbData 매개 변수는 키가 포함된 버퍼의 주소입니다. 이 버퍼는 키와 길이가 같아야 합니다. 이 속성은 DES 키에만 적용됩니다.
KP_PADDING
패딩 모드를 설정합니다. pbData 매개 변수는 암호사용되는 패딩 메서드를 식별하는 숫자 식별자를 수신하는 DWORD 값에 대한 포인터입니다. 다음 값 중 하나일 수 있습니다.
PKCS5_PADDING
PKCS 5(초 6.2) 패딩 메서드를 지정합니다.
RANDOM_PADDING
안쪽 여백은 난수를 사용합니다. 이 패딩 메서드는 Microsoft 제공 CSP에서 지원되지 않습니다.
ZERO_PADDING
안쪽 여백은 0을 사용합니다. 이 패딩 메서드는 Microsoft 제공 CSP에서 지원되지 않습니다.
KP_MODE
pbData 사용할 암호 모드 지정하는 DWORD 값을 가리킵니다. 정의된 암호 모드 목록은 CryptGetKeyParam참조하세요. 암호화 모드는 Microsoft 기본 암호화 공급자에 대해 기본적으로 CRYPT_MODE_CBC 설정됩니다.
KP_MODE_BITS
pbDataOFB(출력 피드백) 또는 CFB(암호 피드백) 암호화 모드를 사용할 때 주기당 처리되는 비트 수를 나타내는 DWORD 값을 가리킵니다. 주기당 처리되는 비트 수는 Microsoft 기본 암호화 공급자에 대해 기본적으로 8로 설정됩니다.
 

hKey 매개 변수에 RSA 키가 지정된 경우 dwParam 매개 변수 값은 다음 값이 될 수 있습니다.

의미
KP_OAEP_PARAMS
키에 대한 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에 의해 생성됩니다. 몇 가지 가능한 오류 코드는 다음과 같습니다.

반환 코드 묘사
ERROR_BUSY
CSP 컨텍스트는 현재 다른 프로세스사용 중입니다.
ERROR_INVALID_HANDLE
매개 변수 중 하나는 유효하지 않은 핸들을 지정합니다.
ERROR_INVALID_PARAMETER
매개 변수 중 하나에 유효하지 않은 값이 포함되어 있습니다. 이는 가장 자주 유효하지 않은 포인터입니다.
NTE_BAD_FLAGS
dwFlags 매개 변수가 0이 아니거나 pbData 버퍼에 유효하지 않은 값이 포함되어 있습니다.
NTE_BAD_TYPE
dwParam 매개 변수는 알 수 없는 매개 변수를 지정합니다.
NTE_BAD_UID
hKey 키를 만들 때 지정된 CSP 컨텍스트를 찾을 수 없습니다.
NTE_FAIL
함수가 예기치 않은 방식으로 실패했습니다.
NTE_FIXEDPARAMETER
일부 CSP에는 하드 코딩된 P, Q 및 G 값이 있습니다. 이 경우 KP_P, KP_Q 및 KP_G dwParam 값을 사용하면 이 오류가 발생합니다.

발언

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

참고 항목

ALG_ID

CryptGenKey

CryptGetKeyParam

CryptImportKey

키 생성 및 Exchange 함수