CryptMsgOpenToEncode-Funktion (wincrypt.h)

Artikel
03/03/2024

Die Funktion CryptMsgOpenToEncode öffnet eine kryptografische Nachricht für die Codierung und gibt ein Handle der geöffneten Nachricht zurück. Die Nachricht bleibt geöffnet, bis CryptMsgClose aufgerufen wird.

Syntax

HCRYPTMSG CryptMsgOpenToEncode(
  [in]           DWORD             dwMsgEncodingType,
  [in]           DWORD             dwFlags,
  [in]           DWORD             dwMsgType,
  [in]           void const        *pvMsgEncodeInfo,
  [in, optional] LPSTR             pszInnerContentObjID,
  [in]           PCMSG_STREAM_INFO pStreamInfo
);

Parameter

[in] dwMsgEncodingType

Gibt den verwendeten Codierungstyp an. Es ist immer akzeptabel, sowohl den Zertifikat- als auch den Nachrichtencodierungstyp anzugeben, indem sie mit einem bitweisen OR-Vorgang kombiniert werden, wie im folgenden Beispiel gezeigt:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

Derzeit definierte Codierungstypen sind:

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFlags

Aktuell definierte dwFlags sind in der folgenden Tabelle dargestellt.

Wert	Bedeutung
CMSG_BARE_CONTENT_FLAG	Die gestreamte Ausgabe verfügt nicht über einen äußeren ContentInfo-Wrapper (gemäß PKCS #7). Dies macht es geeignet, in eine eingeschlossene Nachricht gestreamt zu werden.
CMSG_DETACHED_FLAG	Für die nachfolgenden Aufrufe von CryptMsgUpdate werden getrennte Daten bereitgestellt.
CMSG_AUTHENTICATED_ATTRIBUTES_FLAG	Authentifizierte Attribute müssen in die SignerInfo (wie von PKCS #7 definiert) eingeschlossen werden, wenn sie andernfalls nicht erforderlich wären.
CMSG_CONTENTS_OCTETS_FLAG	Wird beim Berechnen der Größe einer Nachricht verwendet, die mithilfe von Distinguished Encoding Rules (DER) codiert wurde und die in einer umhüllten Nachricht geschachtelt ist. Dies ist besonders nützlich beim Streaming.
CMSG_CMS_ENCAPSULATED_CONTENT_FLAG	Wenn festgelegt wird, wird der innere Inhalt eines Nicht-Datentyps in einem OCTET STRING gekapselt. Gilt sowohl für signierte als auch für umhüllte Nachrichten.
CMSG_CRYPT_RELEASE_CONTEXT_FLAG	Wenn festgelegt, wird der an diese Funktion übergebene hCryptProv für das endgültige CryptMsgUpdate freigegeben. Das Handle wird nicht freigegeben, wenn die Funktion fehlschlägt. Hinweis Die hCryptProvs der Umschlagempfänger werden nicht freigegeben.

[in] dwMsgType

Gibt den Typ der Nachricht an: Dies muss einer der folgenden Werte sein.

Wert	Bedeutung
CMSG_DATA	Dieser Wert wird nicht verwendet.
CMSG_SIGNED	Der parameter pvMsgEncodeInfo ist die Adresse einer CMSG_SIGNED_ENCODE_INFO Struktur, die die Codierungsinformationen enthält.
CMSG_ENVELOPED	Der parameter pvMsgEncodeInfo ist die Adresse einer CMSG_ENVELOPED_ENCODE_INFO-Struktur , die die Codierungsinformationen enthält.
CMSG_SIGNED_AND_ENVELOPED	Dieser Wert ist derzeit nicht implementiert.
CMSG_HASHED	Der parameter pvMsgEncodeInfo ist die Adresse einer CMSG_HASHED_ENCODE_INFO Struktur, die die Codierungsinformationen enthält.

[in] pvMsgEncodeInfo

Die Adresse einer Struktur, die die Codierungsinformationen enthält. Der Datentyp hängt vom Wert des dwMsgType-Parameters ab. Ausführliche Informationen finden Sie unter dwMsgType.

[in, optional] pszInnerContentObjID

Wenn CryptMsgCalculateEncodedLength aufgerufen wird und die Daten für CryptMsgUpdate bereits nachrichtencodiert wurden, wird der entsprechende Objektbezeichner (OID) in pszInnerContentObjID übergeben. Wenn pszInnerContentObjIDNULL ist, wird davon ausgegangen, dass der innere Inhaltstyp zuvor nicht codiert wurde und daher als Oktettzeichenfolge codiert ist und dem Typ CMSG_DATA.

Hinweis Wenn Streaming verwendet wird, muss pszInnerContentObjID entweder NULL oder szOID_RSA_data sein.

Die folgenden Algorithmus-OIDs werden häufig verwendet. Ein Benutzer kann neue innere Inhaltsverwendung definieren, indem er sicherstellt, dass Absender und Empfänger der Nachricht mit der Semantik übereinstimmen, die der OID zugeordnet ist.

szOID_RSA_data
szOID_RSA_signedData
szOID_RSA_envelopedData
szOID_RSA_signEnvData
szOID_RSA_digestedData
szOID_RSA_encryptedData
SPC_INDIRECT_DATA_OBJID

[in] pStreamInfo

Wenn Streaming verwendet wird, ist dieser Parameter die Adresse einer CMSG_STREAM_INFO-Struktur . Die vom pfnStreamOutput-Member der CMSG_STREAM_INFO-Struktur angegebene Rückruffunktion wird aufgerufen, wenn CryptMsgUpdate ausgeführt wird. Der Rückruf wird die codierten Bytes übergeben, die sich aus der Codierung ergeben. Weitere Informationen zur Verwendung des Rückrufs finden Sie unter CMSG_STREAM_INFO.

Hinweis Wenn Streaming verwendet wird, darf die Anwendung keine Datenhandles freigeben, die im parameter pvMsgEncodeInfo übergeben werden, z. B. das Anbieterhandle im hCryptProv-Member der CMSG_SIGNER_ENCODE_INFO-Struktur , bis das von dieser Funktion zurückgegebene Nachrichtenhandle mithilfe der Funktion CryptMsgClose geschlossen wurde.

Wenn das Streaming nicht verwendet wird, wird dieser Parameter auf NULL festgelegt.

Streaming wird nicht mit dem CMSG_HASHED Nachrichtentyp verwendet. Beim Umgang mit Hashdaten muss dieser Parameter auf NULL festgelegt werden.

Betrachten Sie den Fall, dass eine signierte Nachricht in eine umhüllte Nachricht eingeschlossen ist. Die codierte Ausgabe der gestreamten Codierung der signierten Nachricht wird in eine andere Streamingcodierung der umhüllten Nachricht übertragen. Der Rückruf für die Streamingcodierung ruft CryptMsgUpdate auf, um die umhüllte Nachricht zu codieren. Der Rückruf für die umhüllte Nachricht empfängt die codierten Bytes der geschachtelten signierten Nachricht.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt sie ein Handle an die geöffnete Nachricht zurück. Dieses Handle muss geschlossen werden, wenn es nicht mehr benötigt wird, indem es an die Funktion CryptMsgClose übergeben wird.

Wenn diese Funktion fehlschlägt, wird NULL zurückgegeben.

Verwenden Sie zum Abrufen erweiterter Fehlerinformationen die GetLastError-Funktion .

In der folgenden Tabelle sind die Fehlercodes aufgeführt, die am häufigsten von der GetLastError-Funktion zurückgegeben werden.

Rückgabecode	Beschreibung
CRYPT_E_INVALID_MSG_TYPE	Ungültiger Nachrichtentyp.
CRYPT_E_OID_FORMAT	Die OID ist schlecht formatiert.
CRYPT_E_UNKNOWN_ALGO	Der kryptografische Algorithmus ist unbekannt.
E_INVALIDARG	Mindestens ein Argument ist ungültig.
E_OUTOFMEMORY	Es ist nicht genügend Arbeitsspeicher vorhanden.

Wenn dwMsgType CMSG_SIGNED ist, können Außerdem Fehler von CryptCreateHash weitergegeben werden.

Wenn dwMsgType CMSG_ENVELOPED ist, können Fehler aus CryptGenKey, CryptImportKey und CryptExportKey weitergegeben werden.

Wenn dwMsgType CMSG_HASHED ist, können Fehler von CryptCreateHash weitergegeben werden.

Hinweise

Für Funktionen, die die Verschlüsselung ausführen, werden die verschlüsselten symmetrischen Schlüssel vom Little-Endian-Format in das Big-Endian-Format umgekehrt, nachdem CryptExportKey intern aufgerufen wurde. Bei Funktionen, die entschlüsselt werden, werden die verschlüsselten symmetrischen Schlüssel vom Big-End-Format in das Little-Endian-Format umgekehrt, bevor CryptImportKey aufgerufen wird.

CRYPT_NO_SALT wird angegeben, wenn symmetrische Schlüssel mit CryptGenKey und CryptImportKey generiert und importiert werden.

Nachrichten, die mit dem RC2-Verschlüsselungsalgorithmus verschlüsselt wurden, verwenden KP_EFFECTIVE_KEYLEN mit CryptGetKeyParam , um die effektive Schlüssellänge des RC2-Schlüssels zu bestimmen, der Schlüssel importiert oder exportiert.

Für Nachrichten, die mit dem RC2-Verschlüsselungsalgorithmus verschlüsselt wurden, wurden Codierungs- und Decodierungsvorgänge aktualisiert, um ASN RC2-Parameter für das ContentEncryptionAlgorithm-Element der CMSG_ENVELOPED_ENCODE_INFO-Struktur zu verarbeiten.

Für Nachrichten, die mit den Verschlüsselungsalgorithmen RC4, DES und 3DES verschlüsselt wurden, verarbeiten Codierungs- und Decodierungsvorgänge jetzt den ASN IV-Oktettzeichenfolgenparameter für das ContentEncryptionAlgorithm-Element der CMSG_ENVELOPED_ENCODE_INFO-Struktur .

Beispiele

Beispiele, die diese Funktion verwenden, finden Sie unter Beispiel C-Programm: Signieren, Codieren, Decodieren und Überprüfen einer Nachricht, Alternativer Code zum Codieren einer umhüllten Nachricht, Beispiel C-Programm: Codieren einer umhüllten, signierten Nachricht und Beispiel C-Programm: Codieren und Decodieren einer Hashnachricht.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	wincrypt.h
Bibliothek	Crypt32.lib
DLL	Crypt32.dll