CryptEncrypt-Funktion (wincrypt.h)

Artikel
07/16/2024

Wichtige Diese API ist veraltet. Neue und vorhandene Software sollten mit der Verwendung Kryptografie-APIs der nächsten Generation beginnen. Microsoft kann diese API in zukünftigen Versionen entfernen.

Die CryptEncrypt Funktion verschlüsselt Daten. Der Algorithmus, der zum Verschlüsseln der Daten verwendet wird, wird vom Schlüssel des CSP-Moduls bestimmt und vom hKey-Parameter referenziert.

Wichtige Änderungen zur Unterstützung von Secure/Multipurpose Internet Mail Extensions (S/MIME) E-Mail-Interoperabilität wurden an CryptoAPI vorgenommen, die sich auf die Behandlung von umschlägen Nachrichten auswirken. Weitere Informationen finden Sie im Abschnitt "Hinweise" von CryptMsgOpenToEncode.

Wichtig Die CryptEncrypt Funktion ist nicht garantiert threadsicher und gibt möglicherweise falsche Ergebnisse zurück, wenn sie gleichzeitig von mehreren Aufrufern aufgerufen werden.

Syntax

BOOL CryptEncrypt(
  [in]      HCRYPTKEY  hKey,
  [in]      HCRYPTHASH hHash,
  [in]      BOOL       Final,
  [in]      DWORD      dwFlags,
  [in, out] BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen,
  [in]      DWORD      dwBufLen
);

Parameter

[in] hKey

Ein Handle zum Verschlüsselungsschlüssel. Eine Anwendung ruft dieses Handle entweder mithilfe der CryptGenKey- oder der CryptImportKey-Funktion ab.

Der Schlüssel gibt den verwendeten Verschlüsselungsalgorithmus an.

[in] hHash

Ein Handle zu einem Hashobjekt. Wenn Daten gleichzeitig mit Hash versehen und verschlüsselt werden sollen, kann ein Handle zu einem Hashobjekt im hHash--Parameter übergeben werden. Der Hashwert wird mit dem übergebenen Nur-Text- aktualisiert. Diese Option ist nützlich, wenn signierter und verschlüsselter Text generiert wird.

Vor dem Aufrufen CryptEncryptmuss die Anwendung ein Handle für das Hashobjekt abrufen, indem sie die CryptCreateHash--Funktion aufruft. Nach Abschluss der Verschlüsselung kann der Hashwert mithilfe der CryptGetHashParam--Funktion abgerufen werden, oder der Hash kann mithilfe der CryptSignHash--Funktion signiert werden.

Wenn kein Hash ausgeführt werden soll, muss dieser Parameter NULL-sein.

[in] Final

Ein boolescher Wert, der angibt, ob dies der letzte Abschnitt in einer Datenreihe ist, die verschlüsselt wird. Endgültigen wird für den letzten oder einzigen Block auf "TRUE" und auf FALSE- festgelegt, wenn weitere zu verschlüsselnde Blöcke vorhanden sind. Weitere Informationen finden Sie in den Hinweisen.

[in] dwFlags

Der folgende dwFlags Werts ist definiert, ist jedoch für die zukünftige Verwendung reserviert.

Wert	Bedeutung
CRYPT_OAEP	Verwenden Sie optimalen asymmetrischen Verschlüsselungsabstand (OAEP) (PKCS #1 Version 2). Dieses Kennzeichen wird nur vom Microsoft Enhanced Cryptographic Provider mit RSA-Verschlüsselung/Entschlüsselung unterstützt.

[in, out] pbData

Ein Zeiger auf einen Puffer, der den zu verschlüsselnden Nur-Text enthält. Der Nur-Text in diesem Puffer wird mit dem von dieser Funktion erstellten Chiffretext überschrieben.

Der pdwDataLen-Parameter verweist auf eine Variable, die die Länge (in Byte) des Nur-Text-Objekts enthält. Der dwBufLen Parameter enthält die Gesamtgröße dieses Puffers in Byte.

Wenn dieser Parameter NULL-enthält, berechnet diese Funktion die erforderliche Größe für den Chiffretext und platziert diese in dem Wert, auf den der pdwDataLen-Parameter verweist.

[in, out] pdwDataLen

Ein Zeiger auf einen DWORD- Wert, der beim Eintrag die Länge des Nurtexts im PbData- Puffer in Bytes enthält. Beim Beenden enthält dieses DWORD- die Länge des in Byte geschriebenen Chiffretexts in den PbData- Puffer.

Wenn der für PbData- zugewiesene Puffer nicht groß genug ist, um die verschlüsselten Daten zu speichern, gibt GetLastErrorERROR_MORE_DATA zurück und speichert die erforderliche Puffergröße in Byte im DWORD- Wert, auf den pdwDataLenverweist.

Wenn pbData-NULL-ist, wird kein Fehler zurückgegeben, und die Funktion speichert die Größe der verschlüsselten Daten in Bytes im DWORD- Wert, auf den pdwDataLenverweist. Auf diese Weise kann eine Anwendung die richtige Puffergröße ermitteln.

Wenn eine Blockchiffre verwendet wird, muss diese Datenlänge ein Vielfaches der Blockgröße sein, es sei denn, dies ist der letzte zu verschlüsselnde Datenabschnitt, und der parameter Final ist TRUE.

[in] dwBufLen

Gibt die Gesamtgröße des Eingabe-PbData- Puffers in Byte an.

Beachten Sie, dass der verschlüsselte Text je nach verwendetem Algorithmus größer als der ursprüngliche Nur-Text sein kann. In diesem Fall muss der PbData- Puffer groß genug sein, um den verschlüsselten Text und alle Abstände zu enthalten.

Wenn eine Datenstromchiffre verwendet wird, ist der Chiffretext in der Regel die gleiche Größe wie der Nur-Text. Wenn eine Blockchiffre verwendet wird, liegt der Chiffretext bei einer Blocklänge, die größer als der Nur-Text ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion nonzero (TRUE) zurück.

Wenn die Funktion fehlschlägt, wird null (FALSE) zurückgegeben. Rufen Sie für erweiterte Fehlerinformationen GetLastError-auf.

Die von NTE vorgestellten Fehlercodes werden von dem verwendeten CSP generiert. Einige mögliche Fehlercodes folgen.

Wert	Beschreibung
ERROR_INVALID_HANDLE	Einer der Parameter gibt ein ungültiges Handle an.
ERROR_INVALID_PARAMETER	Einer der Parameter enthält einen ungültigen Wert. Dies ist am häufigsten ein ungültiger Zeiger.
NTE_BAD_ALGID	Der hKeySitzungsschlüssel gibt einen Algorithmus an, den dieser CSP nicht unterstützt.
NTE_BAD_DATA	Die zu verschlüsselnden Daten sind ungültig. Wenn beispielsweise eine Blockchiffre verwendet wird und das Final Flag FALSEist, muss der durch pdwDataLen- angegebene Wert ein Vielfaches der Blockgröße sein.
NTE_BAD_FLAGS	Der dwFlags Parameter ist nonzero.
NTE_BAD_HASH	Der hHash--Parameter enthält ein ungültiges Handle.
NTE_BAD_HASH_STATE	Es wurde versucht, Daten zu einem Hashobjekt hinzuzufügen, das bereits als "fertig" gekennzeichnet ist.
NTE_BAD_KEY	Der hKey--Parameter enthält keinen gültigen Handle für einen Schlüssel.
NTE_BAD_LEN	Die Größe des Ausgabepuffers ist zu klein, um den generierten Chiffretext zu speichern.
NTE_BAD_UID	Der CSP-Kontext, der beim Erstellen des Schlüssels angegeben wurde, kann nicht gefunden werden.
NTE_DOUBLE_ENCRYPT	Die Anwendung hat versucht, die gleichen Daten zweimal zu verschlüsseln.
NTE_FAIL	Die Funktion konnte auf unerwartete Weise nicht ausgeführt werden.
NTE_NO_MEMORY	Während des Vorgangs ist der CSP nicht mehr genügend Arbeitsspeicher vorhanden.

Bemerkungen

Wenn eine große Menge an Daten verschlüsselt werden soll, kann sie in Abschnitten durch Aufrufen CryptEncrypt wiederholt erfolgen. Der Parameter Final muss auf TRUE für den letzten Aufruf von CryptEncryptfestgelegt werden, damit das Verschlüsselungsmodul den Verschlüsselungsprozess ordnungsgemäß abschließen kann. Die folgenden zusätzlichen Aktionen werden ausgeführt, wenn FinalTRUEist:

Wenn es sich bei dem Schlüssel um einen Blockchiffreschlüssel handelt, werden die Daten auf ein Vielfaches der Blockgröße der Chiffre aufgefüllt. Wenn die Datenlänge der Blockgröße der Chiffre entspricht, wird ein zusätzlicher Abstandsblock an die Daten angefügt. Um die Blockgröße einer Chiffre zu finden, verwenden Sie CryptGetKeyParam-, um den KP_BLOCKLEN Wert des Schlüssels abzurufen.
Wenn die Verschlüsselung in einem Verkettungsmodusausgeführt wird, setzt der nächste CryptEncrypt Vorgang das Feedbackregister der Verschlüsselung auf den KP_IV Wert des Schlüssels zurück.
Wenn es sich bei der Chiffre um eine Streamchiffrehandelt, setzt die nächste CryptEncrypt die Chiffre auf den ursprünglichen Zustandzurück.

Es gibt keine Möglichkeit, das Feedbackregister der Chiffre auf den KP_IV Wert des Schlüssels festzulegen, ohne den Parameter Final auf TRUEfestzulegen. Wenn dies erforderlich ist, können Sie dies simulieren, indem Sie mithilfe der CryptDuplicateKey--Funktion einen zusätzlichen Abstandsblock hinzufügen oder die Größe jedes Blocks ändern möchten, indem Sie ein Duplikat des ursprünglichen Schlüssels erstellen, indem Sie die funktion CryptDuplicateKey verwenden und den doppelten Schlüssel an die CryptEncrypt-Funktion übergeben. Dies bewirkt, dass die KP_IV des ursprünglichen Schlüssels in den doppelten Schlüssel eingefügt wird. Nachdem Sie den ursprünglichen Schlüssel erstellt oder importiert haben, können Sie den ursprünglichen Schlüssel nicht für die Verschlüsselung verwenden, da das Feedbackregister des Schlüssels geändert wird. Der folgende Pseudocode zeigt, wie dies geschehen kann.

// Set the IV for the original key. Do not use the original key for 
// encryption or decryption after doing this because the key's 
// feedback register will get modified and you cannot change it.
CryptSetKeyParam(hOriginalKey, KP_IV, newIV)

while(block = NextBlock())
{
    // Create a duplicate of the original key. This causes the 
    // original key's IV to be copied into the duplicate key's 
    // feedback register.
    hDuplicateKey = CryptDuplicateKey(hOriginalKey)

    // Encrypt the block with the duplicate key.
    CryptEncrypt(hDuplicateKey, block)

    // Destroy the duplicate key. Its feedback register has been 
    // modified by the CryptEncrypt function, so it cannot be used
    // again. It will be re-duplicated in the next iteration of the 
    // loop.
    CryptDestroyKey(hDuplicateKey)
}

Der Microsoft Enhanced Cryptographic Provider unterstützt die direkte Verschlüsselung mit RSA öffentlichen Schlüsseln und Entschlüsselung mit RSA privaten Schlüsseln. Die Verschlüsselung verwendet PKCS #1 Abstand. Bei der Entschlüsselung wird dieser Abstand überprüft. Die Länge von Nur-Text-Daten, die mit einem Aufruf von CryptEncrypt mit einem RSA-Schlüssel verschlüsselt werden können, ist die Länge des Schlüsselmoduls minus elf Bytes. Die elf Bytes sind das für PKCS #1 Abstand ausgewählte Minimum. Der Chiffretext wird im little-endian--Format zurückgegeben.

Beispiele

Beispiele, die diese Funktion verwenden, finden Sie unter Beispiel-C-Programm: Verschlüsseln einer Datei und Beispiel-C-Programm: Entschlüsseln einer Datei.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	wincrypt.h
Library	Advapi32.lib
DLL-	Advapi32.dll