다음을 통해 공유

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 키를 가져올 수 있습니다. 이 플래그를 설정하지 않으면 16바이트보다 큰 RC2 키가 있는 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를 업그레이드해야 했음을 나타냅니다.

발언

Hash-Based 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(Data Encryption Standard) 키 순열의 경우 패리티 비트를 포함한 전체 키 크기만 가져올 수 있습니다.

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

알고리즘 지원되는 키 크기
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 함수