다음을 통해 공유

CryptImportKey 함수(wincrypt.h)

  • 아티클
중요 이 API는 더 이상 사용되지 않습니다. 신규 및 기존 소프트웨어는 암호화 차세대 API 사용을 시작해야 합니다. Microsoft는 이후 릴리스에서 이 API를 제거할 수 있습니다.
 
CryptImportKey 함수는 암호화 키를키 BLOB에서 CSP(암호화 서비스 공급자)로 전송합니다. 이 함수는 Schannel세션 키, 일반 세션 키, 공개 키 또는 퍼블릭/프라이빗 키 쌍을 가져오는 데 사용할 수 있습니다. 공개 키를 제외한 모든 경우 키 또는 키 쌍이 암호화됩니다.

구문

BOOL CryptImportKey(
  [in]  HCRYPTPROV hProv,
  [in]  const BYTE *pbData,
  [in]  DWORD      dwDataLen,
  [in]  HCRYPTKEY  hPubKey,
  [in]  DWORD      dwFlags,
  [out] HCRYPTKEY  *phKey
);

매개 변수

[in] hProv

CryptAcquireContext 함수를 사용하여 가져온 CSP의 핸들입니다.

[in] pbData

PUBLICKEYSTRUC BLOB 헤더와 암호화된 키가 포함된 BYTE 배열입니다. 이 키 BLOB은 CryptExportKey 함수(이 애플리케이션 또는 다른 컴퓨터에서 실행 중인 다른 애플리케이션)에 의해 만들어집니다.

[in] dwDataLen

키 BLOB의 길이(바이트)를 포함합니다.

[in] hPubKey

pbData에 저장된 키를 해독하는 암호화 키에 대한 핸들입니다. 이 키는 hProv 가 참조하는 동일한 CSP에서 와야 합니다. 이 매개 변수의 의미는 CSP 형식 및 가져올 키 BLOB의 형식에 따라 다릅니다.

  • 키 BLOB이 키 교환 키 쌍(예: SIMPLEBLOB)으로 암호화되는 경우 이 매개 변수는 키 교환 키에 대한 핸들일 수 있습니다.
  • 키 BLOB이 세션 키(예: 암호화된 PRIVATEKEYBLOB)로 암호화된 경우 이 매개 변수에는 이 세션 키의 핸들이 포함됩니다.
  • 키 BLOB이 암호화되지 않은 경우(예: PUBLICKEYBLOB) 이 매개 변수는 사용되지 않으며 0이어야 합니다.
  • 키 BLOB이 Schannel CSP의 세션 키(예: 암호화된 OPAQUEKEYBLOB 또는 다른 공급업체별 OPAQUEKEYBLOB)로 암호화되는 경우 이 매개 변수는 사용되지 않으며 0으로 설정해야 합니다.
참고 일부 CSP는 작업의 결과로 이 매개 변수를 수정할 수 있습니다. 이후에 다른 용도로 이 키를 사용하는 애플리케이션은 CryptDuplicateKey 함수를 호출하여 중복 키 핸들을 만들어야 합니다. 애플리케이션이 핸들 사용을 완료하면 CryptDestroyKey 함수를 호출하여 해제합니다.
 

[in] dwFlags

현재는 PRIVATEKEYBLOB 형식의 퍼블릭/프라이빗 키 쌍을 CSP로 가져올 때만 사용됩니다.

이 매개 변수는 다음 값 중 하나일 수 있습니다.

값 의미
CRYPT_EXPORTABLE
 가져올 키는 결국 다시 적용됩니다. 이 플래그를 사용하지 않으면 키 핸들을 사용하여 CryptExportKey 에 대한 호출이 실패합니다.
CRYPT_OAEP
 이 플래그를 사용하면 SIMPLEBLOB을 가져올 때 RSA 암호화 및 암호 해독을 사용하여 PKCS #1 버전 2 서식을 검사합니다.
CRYPT_NO_SALT
 40비트 대칭 키에 솔트 없음 값이 할당됩니다. 자세한 내용은 솔트 값 기능을 참조하세요.
CRYPT_USER_PROTECTED
 이 플래그가 설정된 경우 CSP는 이 키를 사용하여 특정 작업을 시도할 때 대화 상자 또는 다른 방법을 통해 사용자에게 알 수 있습니다. 정확한 동작은 CSP 또는 사용된 CSP 형식으로 지정됩니다. CRYPT_SILENT 집합을 사용하여 공급자 컨텍스트를 가져온 경우 이 플래그를 사용하면 오류가 발생하고 마지막 오류가 NTE_SILENT_CONTEXT 설정됩니다.
CRYPT_IPSEC_HMAC_KEY
 16바이트보다 큰 RC2 키를 가져올 수 있습니다. 이 플래그를 설정하지 않으면 RC2 키가 16바이트보다 큰 CryptImportKey 함수에 대한 호출이 실패하고 GetLastError 를 호출하면 NTE_BAD_DATA 반환됩니다.

[out] phKey

가져온 키의 핸들을 수신하는 HCRYPTKEY 값에 대한 포인터입니다. 키 사용을 마쳤으면 CryptDestroyKey 함수를 호출하여 핸들을 해제합니다.

반환 값

함수가 성공하면 함수는 0이 아닌 값을 반환합니다.

함수가 실패하면 0을 반환합니다. 확장된 오류 정보는 GetLastError를 호출합니다.

"NTE"가 앞에 있는 오류 코드는 사용 중인 특정 CSP에 의해 생성됩니다. 몇 가지 가능한 오류 코드는 다음과 같습니다.

반환 코드 설명
ERROR_BUSY
 일부 CSP는 다른 스레드 또는 프로세스가 이 키를 사용하는 동안 프라이빗 키를 컨테이너로 가져오는 경우 이 오류를 설정합니다.
ERROR_INVALID_HANDLE
 매개 변수 중 하나는 유효하지 않은 핸들을 지정합니다.
ERROR_INVALID_PARAMETER
 매개 변수 중 하나에는 유효하지 않은 값이 포함되어 있습니다. 이는 가장 자주 유효하지 않은 포인터입니다.
NTE_BAD_ALGID
 가져올 간단한 키 BLOB 은 예상되는 키 교환 알고리즘으로 암호화되지 않습니다.
NTE_BAD_DATA
 가져올 공개 키와 함께 작동하는 알고리즘은 이 CSP에서 지원되지 않거나 공개 키 중 하나가 아닌 다른 항목으로 암호화된 세션 키를 가져오려고 시도했습니다.
NTE_BAD_FLAGS
 지정된 dwFlags 매개 변수가 잘못되었습니다.
NTE_BAD_TYPE
 키 BLOB 형식은 이 CSP에서 지원되지 않으며 유효하지 않을 수 있습니다.
NTE_BAD_UID
 hProv 매개 변수에 유효한 컨텍스트 핸들이 없습니다.
NTE_BAD_VER
 키 BLOB의 버전 번호가 CSP 버전과 일치하지 않습니다. 이는 일반적으로 CSP를 업그레이드해야 했음을 나타냅니다.

설명

HMAC(해시 기반 메시지 인증 코드) 키를 가져올 때 호출자는 가져온 키를 PLAINTEXTKEYBLOB 형식으로 식별하고 PUBLICKEYSTRUC BLOB 헤더의 aiKeyAlg 필드에 적절한 알고리즘 식별자를 설정해야 합니다.

CryptImportKey 함수를 사용하여 대칭 알고리즘에 대한 일반 텍스트 키를 가져올 수 있습니다. 그러나 사용 편의를 위해 CryptGenKey 함수를 대신 사용하는 것이 좋습니다. 일반 텍스트 키를 가져올 때 pbData 매개 변수에 전달되는 키 BLOB의 구조는 PLAINTEXTKEYBLOB입니다.

사용 중인 CSP에서 지원하는 모든 알고리즘 또는 키 조합 유형과 함께 PLAINTEXTKEYBLOB 형식을 사용할 수 있습니다.

일반 텍스트 키를 가져오는 예제는 예제 C 프로그램: 일반 텍스트 키 가져오기를 참조하세요.

다음 예제에서는 헤더 필드를 설정하는 방법을 보여줍니다.

keyBlob.header.bType = PLAINTEXTKEYBLOB;
keyBlob.header.bVersion = CUR_BLOB_VERSION;
keyBlob.header.reserved = 0;
// CALG_AES_128 is used as an example. You would set this to the 
// algorithm id that corresponds to the one used by the key.
keyBlob.header.aiKeyAlg = CALG_AES_128;

키의 길이는 keyBlob.keyLength에 지정되며, 그 뒤에 실제 키 데이터가 표시됩니다.

참고 HMAC 알고리즘에는 자체 알고리즘 식별자가 없습니다. 대신 CALG_RC2 사용합니다. CRYPT_IPSEC_HMAC_KEY RC2 키를 16바이트 이상 가져올 수 있습니다.
 
PLAINTEXTKEYBLOB를 사용하는 DES(데이터 암호화 표준) 키 순열의 경우 패리티 비트를 포함한 전체 키 크기만 가져올 수 있습니다.

지원되는 키 크기는 다음과 같습니다.

알고리즘 지원되는 키 크기
CALG_DES 64비트
CALG_3DES_112 128비트
CALG_3DES 192비트
 

예제

다음 예제에서는 키 BLOB에서 키를 가져오는 방법을 보여줍니다. 이 함수에 대한 전체 예제는 예제 C 프로그램: 해시 서명 및 해시 서명 확인을 참조하세요. 이 함수를 사용하는 추가 코드는 예제 C 프로그램: 파일 암호 해독을 참조하세요.

#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>

BOOL ImportKey(HCRYPTPROV hProv, LPBYTE pbKeyBlob, DWORD dwBlobLen)
{
    HCRYPTKEY hPubKey;

    //---------------------------------------------------------------
    // This code assumes that a cryptographic provider (hProv) 
    // has been acquired and that a key BLOB (pbKeyBlob) that is 
    // dwBlobLen bytes long has been acquired. 

    //---------------------------------------------------------------
    // Get the public key of the user who created the digital 
    // signature and import it into the CSP by using CryptImportKey. 
    // The key to be imported is in the buffer pbKeyBlob that is  
    // dwBlobLen bytes long. This function returns a handle to the 
    // public key in hPubKey.

    if(CryptImportKey(
        hProv,
        pbKeyBlob,
        dwBlobLen,
        0,
        0,
        &hPubKey))
    {
        printf("The key has been imported.\n");
    }
    else
    {
        printf("Public key import failed.\n");
        return FALSE;
    }

    //---------------------------------------------------------------
    // Insert code that uses the imported public key here.
    //---------------------------------------------------------------

    //---------------------------------------------------------------
    // When you have finished using the key, you must release it.
    if(CryptDestroyKey(hPubKey))
    {
        printf("The public key has been released.");
    }
    else
    {
        printf("The public key has not been released.");
        return FALSE;
    }

    return TRUE;
}

요구 사항

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

추가 정보

CryptAcquireContext

CryptDestroyKey

CryptExportKey

키 생성 및 Exchange 함수