EncryptMessage (General), funkcja

Funkcja EncryptMessage (Ogólne) szyfruje komunikat w celu zapewnienia prywatności. Funkcja EncryptMessage (ogólne) umożliwia aplikacji wybór spośród algorytmów kryptograficznych obsługiwanych przez wybrany mechanizm. Funkcja EncryptMessage (Ogólne) używa kontekstu zabezpieczeń , do których odwołuje się do uchwytu kontekstu. Niektóre pakiety nie mają komunikatów do szyfrowania ani odszyfrowywania, ale raczej zapewniają skrót integralności, który można sprawdzić.

W przypadku korzystania z dostawcy obsługi zabezpieczeń skrótów (SSP) ta funkcja jest dostępna tylko jako mechanizm SASL.

W przypadku korzystania z dostawcy SSP Schannel ta funkcja szyfruje komunikaty przy użyciu klucza sesji wynegocjowanego z partią zdalną, która otrzyma komunikat. Algorytm szyfrowania jest określany przez używany zestaw [szyfrowania ](szyfrowania suites-in-schannel.md).

Aby uzyskać informacje o korzystaniu z tej funkcji z określonym dostawcą usług udostępnionych, zobacz następujące tematy.

Składnia

SECURITY_STATUS SEC_Entry EncryptMessage(
  _In_    PCtxtHandle    phContext,
  _In_    ULONG          fQOP,
  _Inout_ PSecBufferDesc pMessage,
  _In_    ULONG          MessageSeqNo
);

Parametry

phContext [in]

Dojście do kontekstu zabezpieczeń , który ma być używany do szyfrowania komunikatu.

fQOP [in]

Flagi specyficzne dla pakietu wskazujące jakość ochrony. Pakiet zabezpieczeń może użyć tego parametru, aby umożliwić wybór algorytmów kryptograficznych.

W przypadku korzystania z dostawcy usług udostępnionych skrótów ten parametr musi być ustawiony na zero.

Ten parametr może być jedną z następujących flag.

pMessage [in, out]

Wskaźnik do struktury SecBufferDesc . W danych wejściowych struktura odwołuje się do co najmniej jednej struktury SecBuffer . Jednym z nich może być typ SECBUFFER_DATA. Ten bufor zawiera komunikat do zaszyfrowania. Komunikat jest szyfrowany w miejscu, zastępując oryginalną zawartość struktury.

Funkcja nie przetwarza z atrybutem SECBUFFER_READONLY.

Długość struktury SecBuffer , która zawiera komunikat, nie może być większa niż cbMaximumMessage, która jest uzyskiwana z funkcji QueryContextAttributes (General) (SECPKG_ATTR_STREAM_SIZES).

W przypadku korzystania z dostawcy SSP skrótu musi istnieć drugi bufor typu SECBUFFER_PADDING lub SEC_BUFFER_DATA do przechowywania informacji o podpisie . Aby uzyskać rozmiar buforu wyjściowego, wywołaj funkcję QueryContextAttributes (Ogólne) i określ SECPKG_ATTR_SIZES. Funkcja zwróci strukturę SecPkgContext_Sizes . Rozmiar buforu wyjściowego jest sumą wartości w elementach członkowskich cbMaxSignature i cbBlockSize .

Aplikacje, które nie korzystają z protokołu SSL, muszą dostarczyć secBuffer typu SECBUFFER_PADDING.

MessageSeqNo [in]

Numer sekwencji przypisany do komunikatu przez aplikację transportu. Jeśli aplikacja transportowa nie obsługuje numerów sekwencji, ten parametr musi mieć wartość zero.

W przypadku korzystania z dostawcy usług udostępnionych skrótów ten parametr musi być ustawiony na zero. Skrót dostawcy usług udostępnionych zarządza numerowaniem sekwencji wewnętrznie.

W przypadku korzystania z dostawcy SSP Schannel ten parametr musi być ustawiony na zero. Dostawca SSP Schannel nie używa numerów sekwencji.

Wartość zwracana

Jeśli funkcja powiedzie się, funkcja zwróci SEC_E_OK.

Jeśli funkcja zakończy się niepowodzeniem, zwraca jeden z następujących kodów błędów.

Uwagi

Funkcja EncryptMessage (Ogólne) szyfruje komunikat na podstawie komunikatu i klucza sesji z kontekstu zabezpieczeń.

Jeśli aplikacja transportowa utworzyła kontekst zabezpieczeń do obsługi wykrywania sekwencji, a obiekt wywołujący udostępnia numer sekwencji, funkcja zawiera te informacje z zaszyfrowanym komunikatem. Dołączenie tych informacji chroni przed odtwarzaniem, wstawianiem i pomijaniem komunikatów. Pakiet zabezpieczeń zawiera numer sekwencji przekazywany z aplikacji transportowej.

Jeśli używasz dostawcy usług udostępnionych skrótów, pobierz rozmiar buforu wyjściowego, wywołując funkcję QueryContextAttributes (Ogólne) i określając SECPKG_ATTR_SIZES. Funkcja zwróci strukturę SecPkgContext_Sizes . Rozmiar buforu wyjściowego jest sumą wartości w elementach członkowskich cbMaxSignature i cbBlockSize .

W przypadku użycia z dostawcą SSP Schannel parametr pMessage musi zawierać strukturę SecBufferDesc z następującymi.

Jeśli używasz dostawcy SSP Schannel, określ maksymalny rozmiar każdego buforu, wywołując funkcję QueryContextAttributes (Ogólne) i określając atrybut SECPKG_ATTR_STREAM_SIZES. Ta funkcja zwraca SecPkgContext_StreamSizes strukturę, której elementy członkowskie zawierają maksymalne rozmiary nagłówka (elementu członkowskiego cbHeader ), komunikat (element członkowski cbMaximumMessage ) i przyczepy (składowa cbTrailer ).

Aby uzyskać optymalną wydajność, struktury pMessage powinny być przydzielane z ciągłej pamięci.

Windows XP/2000: Ta funkcja była również znana jako SealMessage. Aplikacje powinny teraz używać tylko funkcji EncryptMessage (ogólne).

Wymagania

Zobacz też

• funkcji SSPI
• AcceptSecurityContext (ogólne)
• DecryptMessage (ogólne)
• InitializeSecurityContext (ogólne)
• QueryContextAttributes (Ogólne)
• SecBuffer
• SecBufferDesc