EncryptMessage 함수(sspi.h)

아티클
03/08/2023

EncryptMessage(다이제스트) 함수는 개인 정보를 제공하기 위해 메시지를 암호화합니다. EncryptMessage(다이제스트) 를 사용하면 애플리케이션이 선택한 메커니즘에서 지원하는 암호화 알고리즘 중에서 선택할 수 있습니다. EncryptMessage(다이제스트) 함수는 컨텍스트 핸들에서 참조하는 보안 컨텍스트를 사용합니다. 일부 패키지에는 암호화 또는 암호 해독할 메시지가 없지만 검사할 수 있는 무결성 해시를 제공합니다.

이 함수는 SASL 메커니즘으로만 사용할 수 있습니다.

참고EncryptMessage(다이제스트) 및 DecryptMessage(다이제스트) 는 한 스레드가 암호화되고 다른 스레드가 암호를 해독하는 경우 단일 SSPI( 보안 지원 공급자 인터페이스 ) 컨텍스트의 두 스레드에서 동시에 호출할 수 있습니다. 둘 이상의 스레드가 암호화 중이거나 둘 이상의 스레드가 암호를 해독하는 경우 각 스레드는 고유한 컨텍스트를 가져와야 합니다.

구문

SECURITY_STATUS SEC_ENTRY EncryptMessage(
  [in]      PCtxtHandle    phContext,
  [in]      unsigned long  fQOP,
  [in, out] PSecBufferDesc pMessage,
  [in]      unsigned long  MessageSeqNo
);

매개 변수

[in] phContext

메시지를 암호화하는 데 사용할 보안 컨텍스트 에 대한 핸들입니다.

[in] fQOP

보호 품질을 나타내는 패키지별 플래그입니다. 보안 패키지는 이 매개 변수를 사용하여 암호화 알고리즘을 선택할 수 있습니다.

다이제스트 SSP를 사용하는 경우 이 매개 변수를 0으로 설정해야 합니다.

[in, out] pMessage

SecBufferDesc 구조체에 대한 포인터입니다. 입력 시 구조체는 SECBUFFER_DATA 형식일 수 있는 하나 이상의 SecBuffer 구조를 참조합니다. 해당 버퍼에는 암호화할 메시지가 포함됩니다. 메시지가 암호화되어 구조체의 원래 내용을 덮어씁니다.

함수는 SECBUFFER_READONLY 특성으로 버퍼를 처리하지 않습니다.

메시지를 포함하는 SecBuffer 구조체의 길이는 queryContextAttributes(Digest)(SECPKG_ATTR_STREAM_SIZES) 함수에서 가져온 cbMaximumMessage보다 크지 않아야 합니다.

다이제스트 SSP를 사용하는 경우 서명 정보를 보유하려면 SECBUFFER_PADDING 또는 SEC_BUFFER_DATA 형식의 두 번째 버퍼가 있어야 합니다. 출력 버퍼의 크기를 얻으려면 QueryContextAttributes(다이제스트) 함수를 호출하고 SECPKG_ATTR_SIZES 지정합니다. 함수는 SecPkgContext_Sizes 구조를 반환합니다. 출력 버퍼의 크기는 cbMaxSignature 및 cbBlockSize 멤버의 값 합계입니다.

SSL을 사용하지 않는 애플리케이션은 SECBUFFER_PADDING 형식의 SecBuffer 를 제공해야 합니다.

[in] MessageSeqNo

전송 애플리케이션이 메시지에 할당한 시퀀스 번호입니다. 전송 애플리케이션에서 시퀀스 번호를 유지하지 않는 경우 이 매개 변수는 0이어야 합니다.

다이제스트 SSP를 사용하는 경우 이 매개 변수를 0으로 설정해야 합니다. 다이제스트 SSP는 내부적으로 시퀀스 번호 매기기를 관리합니다.

반환 값

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

함수가 실패하면 다음 오류 코드 중 하나를 반환합니다.

반환 코드	설명
SEC_E_BUFFER_TOO_SMALL	출력 버퍼가 너무 작습니다. 자세한 내용은 설명 부분을 참조하세요.
SEC_E_CONTEXT_EXPIRED	애플리케이션이 이미 닫힌 컨텍스트를 참조하고 있습니다. 올바르게 작성된 애플리케이션은 이 오류를 수신하면 안 됩니다.
SEC_E_CRYPTO_SYSTEM_INVALID	보안 컨텍스트에 대해 선택한 암호 는 지원되지 않습니다.
SEC_E_INSUFFICIENT_MEMORY	요청된 작업을 완료하는 데 사용할 수 있는 메모리가 부족합니다.
SEC_E_INVALID_HANDLE	유효하지 않은 컨텍스트 핸들이 phContext 매개 변수에 지정되었습니다.
SEC_E_INVALID_TOKEN	SECBUFFER_DATA 형식 버퍼를 찾을 수 없습니다.
SEC_E_QOP_NOT_SUPPORTED	기밀성이나 무결성 은 보안 컨텍스트에서 지원되지 않습니다.

설명

EncryptMessage(다이제스트) 함수는 보안 컨텍스트의 메시지 및 세션 키를 기반으로 메시지를 암호화합니다.

전송 애플리케이션이 시퀀스 검색을 지원하기 위해 보안 컨텍스트를 만들고 호출자가 시퀀스 번호를 제공하는 경우 함수는 암호화된 메시지와 함께 이 정보를 포함합니다. 이 정보를 포함하면 메시지 재생, 삽입 및 표시 안 함으로부터 보호됩니다. 보안 패키지는 전송 애플리케이션에서 전달된 시퀀스 번호를 통합합니다.

다이제스트 SSP를 사용하는 경우 QueryContextAttributes(다이제스트) 함수를 호출하고 SECPKG_ATTR_SIZES 지정하여 출력 버퍼의 크기를 가져옵니다. 함수는 SecPkgContext_Sizes 구조를 반환합니다. 출력 버퍼의 크기는 cbMaxSignature 및 cbBlockSize 멤버의 값 합계입니다.

참고 이러한 버퍼는 표시된 순서대로 제공해야 합니다.

버퍼 유형	Description
SECBUFFER_STREAM_HEADER	내부적으로 사용됩니다. 초기화가 필요하지 않습니다.
SECBUFFER_DATA	암호화할 일반 텍스트 메시지를 포함합니다.
SECBUFFER_STREAM_TRAILER	내부적으로 사용됩니다. 초기화가 필요하지 않습니다.
SECBUFFER_EMPTY	내부적으로 사용됩니다. 초기화가 필요하지 않습니다. 크기는 0일 수 있습니다.

최적의 성능을 위해 연속 메모리에서 pMessage 구조를 할당해야 합니다.

Windows XP: 이 함수를 SealMessage라고도 합니다. 이제 애플리케이션은 EncryptMessage(다이제스트) 만 사용해야 합니다.

요구 사항


지원되는 최소 클라이언트	Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	sspi.h(Security.h 포함)
라이브러리	Secur32.lib
DLL	Secur32.dll