CryptSignHashA 함수(wincrypt.h)

  • 아티클
중요 이 API는 더 이상 사용되지 않습니다. 신규 및 기존 소프트웨어는 Cryptography Next Generation API 사용을 시작해야 합니다. Microsoft는 향후 릴리스에서 이 API를 제거할 수 있습니다.
 
CryptSignHash 함수는 데이터에 서명합니다. 모든 서명 알고리즘은 비대칭이므로 CryptoAPI는 데이터를 직접 서명하는 것을 허용하지 않습니다. 대신 데이터가 먼저 해시되고CryptSignHash 가 해시에 서명하는 데 사용됩니다.

구문

BOOL CryptSignHashA(
  [in]      HCRYPTHASH hHash,
  [in]      DWORD      dwKeySpec,
  [in]      LPCSTR     szDescription,
  [in]      DWORD      dwFlags,
  [out]     BYTE       *pbSignature,
  [in, out] DWORD      *pdwSigLen
);

매개 변수

[in] hHash

서명할 해시 개체 의 핸들입니다.

[in] dwKeySpec

공급자의 컨테이너에서 사용할 프라이빗 키를 식별합니다. AT_KEYEXCHANGE 또는 AT_SIGNATURE 수 있습니다.

사용된 서명 알고리즘은 키 쌍을 원래 만들 때 지정됩니다.

Microsoft 기본 암호화 공급자가 지원하는 유일한 서명 알고리즘은 RSA 공개 키 알고리즘입니다.

[in] szDescription

이 매개 변수는 더 이상 사용되지 않으며 보안 취약성을 방지하려면 NULL 로 설정해야 합니다. 그러나 Microsoft 기본 암호화 공급자에서 이전 버전과의 호환성을 위해 계속 지원됩니다.

[in] dwFlags

다음 플래그 값이 정의됩니다.

값 의미
CRYPT_NOHASHOID
0x00000001
 RSA 공급자와 함께 사용됩니다. OID(해시 개체 식별자 )는 RSA 공개 키 암호화에 배치되지 않습니다. 이 플래그가 설정되지 않은 경우 기본 서명의 해시 OID는 PKCS #1의 DigestInfo 정의에 지정된 대로 지정됩니다.
CRYPT_TYPE2_FORMAT
0x00000002
 이 플래그는 사용되지 않습니다.
CRYPT_X931_FORMAT
0x00000004
 ANSI X9.31 표준에 지정된 RSA 서명 패딩 메서드를 사용합니다.

[out] pbSignature

서명 데이터를 수신하는 버퍼에 대한 포인터입니다.

이 매개 변수는 메모리 할당을 위해 버퍼 크기를 설정하는 NULL 일 수 있습니다. 자세한 내용은 알 수 없는 길이의 데이터 검색을 참조하세요.

[in, out] pdwSigLen

pbSignature 버퍼의 크기(바이트)를 지정하는 DWORD 값에 대한 포인터입니다. 함수가 반환되면 DWORD 값에는 버퍼에 저장된 바이트 수가 포함됩니다.

참고 버퍼에서 반환된 데이터를 처리할 때 애플리케이션은 반환된 데이터의 실제 크기를 사용해야 합니다. 실제 크기는 입력에 지정된 버퍼의 크기보다 약간 작을 수 있습니다. (입력에서 버퍼 크기는 일반적으로 가능한 가장 큰 출력 데이터가 버퍼에 맞도록 충분히 크게 지정됩니다.) 출력에서 이 매개 변수가 가리키는 변수는 버퍼에 복사된 데이터의 실제 크기를 반영하도록 업데이트됩니다.
 

반환 값

함수가 성공하면 함수는 TRUE를 반환 합니다.

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

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

반환 코드 설명
ERROR_INVALID_HANDLE
 매개 변수 중 하나는 유효하지 않은 핸들을 지정합니다.
ERROR_INVALID_PARAMETER
 매개 변수 중 하나에 유효하지 않은 값이 포함되어 있습니다. 이는 가장 자주 유효하지 않은 포인터입니다.
ERROR_MORE_DATA
 pbSignature 매개 변수로 지정된 버퍼가 반환된 데이터를 저장할 만큼 크지 않습니다. 필요한 버퍼 크기(바이트)는 pdwSigLenDWORD 값에 있습니다.
NTE_BAD_ALGID
 hHash 핸들은 이 CSP가 지원하지 않는 알고리즘을 지정하거나 dwKeySpec 매개 변수에 잘못된 값이 있습니다.
NTE_BAD_FLAGS
 dwFlags 매개 변수가 0이 아닌 경우
NTE_BAD_HASH
 hHash 매개 변수로 지정된 해시 개체가 잘못되었습니다.
NTE_BAD_UID
 해시 개체를 만들 때 지정한 CSP 컨텍스트를 찾을 수 없습니다.
NTE_NO_KEY
 dwKeySpec에서 지정한 프라이빗 키가 없습니다.
NTE_NO_MEMORY
 작업 중에 CSP 메모리가 부족합니다.

설명

이 함수를 호출하기 전에 CryptCreateHash 함수를 호출하여 해시 개체에 대한 핸들을 가져와야 합니다. 그런 다음 CryptHashData 또는 CryptHashSessionKey 함수를 사용하여 해시 개체에 데이터 또는 세션 키를 추가합니다. CryptSignHash 함수는 해시를 완료합니다.

DSS CSP는 MD5 및 SHA 해시 알고리즘 모두에서 해시를 지원하지만 DSS CSP는 SHA 해시 서명만 지원합니다.

이 함수가 호출된 후에는 해시에 더 이상 데이터를 추가할 수 없습니다. CryptHashData 또는 CryptHashSessionKey에 대한 추가 호출이 실패합니다.

애플리케이션이 해시 사용을 완료한 후 CryptDestroyHash 함수를 호출하여 해시 개체를 삭제합니다.

기본적으로 Microsoft RSA 공급자는 서명에 PKCS #1 패딩 메서드를 사용합니다. 서명의 DigestInfo 요소에 있는 해시 OID는 해시 개체와 연결된 알고리즘 OID로 자동으로 설정됩니다. CRYPT_NOHASHOID 플래그를 사용하면 이 OID가 서명에서 생략됩니다.

경우에 따라 다른 곳에서 생성된 해시 값에 서명해야 합니다. 이 작업은 다음 작업 시퀀스를 사용하여 수행할 수 있습니다.

  1. CryptCreateHash를 사용하여 해시 개체를 만듭니다.
  2. CryptSetHashParam에서 dwParam 매개 변수의 HP_HASHVAL 값을 사용하여 해시 개체의 해시 값을 설정합니다.
  3. CryptSignHash를 사용하여 해시 값에 서명하고 디지털 서명 블록을 가져옵니다.
  4. CryptDestroyHash를 사용하여 해시 개체를 삭제합니다.

예제

다음 예제에서는 먼저 서명할 데이터를 해시한 다음 CryptSignHash 함수를 사용하여 해시에 서명하여 데이터에 서명하는 방법을 보여 줍니다.

//-------------------------------------------------------------
// Declare and initialize variables.

HCRYPTPROV hProv;
BYTE *pbBuffer= (BYTE *)"Sample data that is to be signed.";
DWORD dwBufferLen = strlen((char *)pbBuffer)+1;
HCRYPTHASH hHash;

//--------------------------------------------------------------------
// This code assumes that a cryptographic context handle, hProv,
// and a hash handle, hHash, are available.
// For code needed to acquire the context, see "Example C Program: 
// Signing a Hash and Verifying the Hash Signature."

//--------------------------------------------------------------------
// Compute the cryptographic hash of the buffer.

if(CryptHashData(
   hHash, 
   pbBuffer, 
   dwBufferLen, 
   0)) 
{
     printf("The data buffer has been hashed.\n");
}
else
{
     printf("Error during CryptHashData.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Determine the size of the signature and allocate memory.

dwSigLen= 0;
if(CryptSignHash(
   hHash, 
   AT_SIGNATURE, 
   szDescription, 
   0, 
   NULL, 
   &dwSigLen)) 
{
     printf("Signature length %d found.\n",dwSigLen);
}
else
{
     printf("Error during CryptSignHash\n");
     exit(1);
}
//--------------------------------------------------------------------
// Allocate memory for the signature buffer.

if(pbSignature = (BYTE *)malloc(dwSigLen))
{
     printf("Memory allocated for the signature.\n");
}
else
{
     printf("Out of memory\n");
     exit(1);
}
//--------------------------------------------------------------------
// Sign the hash object.

if(CryptSignHash(
   hHash, 
   AT_SIGNATURE, 
   szDescription, 
   0, 
   pbSignature, 
   &dwSigLen)) 
{
     printf("pbSignature is the hash signature.\n");
}
else
{
     printf("Error during CryptSignHash.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Destroy the hash object.

if(hHash) 
  CryptDestroyHash(hHash);

이 코드의 컨텍스트를 포함하는 전체 예제는 예제 C 프로그램: 해시 서명 및 해시 서명 확인을 참조하세요.

참고

wincrypt.h 헤더는 CRYptSignHash를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

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

추가 정보

CryptCreateHash

CryptDestroyHash

CryptHashData

CryptHashSessionKey

CryptVerifySignature

해시 및 디지털 서명 함수