CryptEncrypt-Funktion (wincrypt.h)
Wichtige Änderungen zur Unterstützung der Interoperabilität von Secure/Multipurpose Internet Mail Extensions (S/MIME) wurden an CryptoAPI vorgenommen, die sich auf die Behandlung von umhüllten Nachrichten auswirken. Weitere Informationen finden Sie im Abschnitt Hinweise von CryptMsgOpenToEncode.
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 für den 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 für ein Hashobjekt. Wenn Daten gleichzeitig gehasht und verschlüsselt werden sollen, kann im hHash-Parameter ein Handle an ein Hashobjekt übergeben werden. Der Hashwert wird mit dem übergebenen Klartext aktualisiert. Diese Option ist beim Generieren von signiertem und verschlüsseltem Text nützlich.
Vor dem Aufrufen von CryptEncrypt muss die Anwendung durch Aufrufen der CryptCreateHash-Funktion ein Handle für das Hashobjekt abrufen. Nach Abschluss der Verschlüsselung kann der Hashwert mithilfe der CryptGetHashParam-Funktion abgerufen werden, oder der Hash kann mit 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. Final ist für den letzten oder einzigen Block auf TRUE und auf FALSE festgelegt, wenn weitere Blöcke verschlüsselt werden sollen. Weitere Informationen finden Sie in den Hinweisen.
[in] dwFlags
Der folgende dwFlags-Wert ist definiert, aber für die zukünftige Verwendung reserviert.
| Wert | Bedeutung |
|---|---|
|
Verwenden Sie optimale asymmetrische Verschlüsselungsfüllung (OAEP) (PKCS #1 Version 2). Dieses Flag wird nur vom Microsoft Enhanced Cryptographic Provider mit RSA-Ver-/Entschlüsselung unterstützt. |
[in, out] pbData
Ein Zeiger auf einen Puffer, der den zu verschlüsselnden Klartext enthält. Der Klartext in diesem Puffer wird mit dem von dieser Funktion erstellten Verschlüsselungstext überschrieben.
Der parameter pdwDataLen verweist auf eine Variable, die die Länge des Klartexts in Bytes enthält. Der dwBufLen-Parameter enthält die Gesamtgröße dieses Puffers in Bytes.
Wenn dieser Parameter NULL enthält, berechnet diese Funktion die erforderliche Größe für den Verschlüsselungstext 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 Klartexts im pbData-Puffer in Bytes enthält. Beim Beenden enthält dieses DWORD die Länge des In den pbData-Puffer geschriebenen Verschlüsselungstexts in Bytes.
Wenn der für pbData zugeordnete Puffer nicht groß genug ist, um die verschlüsselten Daten aufzunehmen, gibt GetLastErrorERROR_MORE_DATA zurück und speichert die erforderliche Puffergröße in Bytes im DWORD-Wert , auf den pdwDataLen verweist.
Wenn pbDataNULL ist, wird kein Fehler zurückgegeben, und die Funktion speichert die Größe der verschlüsselten Daten in Bytes im DWORD-Wert , auf den pdwDataLen verweist. Dadurch kann eine Anwendung die richtige Puffergröße bestimmen.
Wenn eine Blockchiffre verwendet wird, muss diese Datenlänge ein Vielfaches der Blockgröße sein, es sei denn, dies ist der letzte Abschnitt der zu verschlüsselnden Daten und der Final-Parameter ist TRUE.
[in] dwBufLen
Gibt die Gesamtgröße des PbData-Eingabepuffers in Bytes an.
Beachten Sie, dass der verschlüsselte Text je nach verwendetem Algorithmus größer sein kann als der ursprüngliche Klartext. In diesem Fall muss der pbData-Puffer groß genug sein, um den verschlüsselten Text und alle Auffüllungen zu enthalten.
Wenn eine Datenstromchiffre verwendet wird, hat der Verschlüsselungstext in der Regel die gleiche Größe wie der Klartext. Wenn eine Blockchiffre verwendet wird, ist der Chiffretext bis zu einer Blocklänge größer als der Klartext.
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt die Funktion ungleich null (TRUE) zurück.
Wenn die Funktion fehlschlägt, gibt sie null (FALSE) zurück. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.
Die von NTE vorangestellten Fehlercodes werden vom jeweiligen verwendeten CSP generiert. Es folgen einige mögliche Fehlercodes.
| Wert | BESCHREIBUNG |
|---|---|
|
Einer der Parameter gibt ein ungültiges Handle an. |
|
Einer der Parameter enthält einen ungültigen Wert. Dies ist in den meisten Fällen ein ungültiger Zeiger. |
|
Der hKey-Sitzungsschlüssel gibt einen Algorithmus an, der von diesem CSP nicht unterstützt wird. |
|
Die zu verschlüsselnden Daten sind ungültig. Wenn beispielsweise eine Blockchiffre verwendet wird und das Final-FlagFALSE ist, muss der von pdwDataLen angegebene Wert ein Vielfaches der Blockgröße sein. |
|
Der dwFlags-Parameter ist ungleich null. |
|
Der hHash-Parameter enthält ein ungültiges Handle. |
|
Es wurde versucht, einem Hashobjekt Daten hinzuzufügen, das bereits als "fertig" gekennzeichnet ist. |
|
Der hKey-Parameter enthält kein gültiges Handle für einen Schlüssel. |
|
Die Größe des Ausgabepuffers ist zu klein, um den generierten Verschlüsselungstext zu speichern. |
|
Der CSP-Kontext, der beim Erstellen des Schlüssels angegeben wurde, kann nicht gefunden werden. |
|
Die Anwendung hat versucht, die gleichen Daten zweimal zu verschlüsseln. |
|
Die Funktion ist auf unerwartete Weise fehlgeschlagen. |
|
Während des Vorgangs war für den CSP der Arbeitsspeicher nicht mehr vorhanden. |
Hinweise
Wenn eine große Datenmenge verschlüsselt werden soll, kann dies in Abschnitten erfolgen, indem CryptEncrypt wiederholt aufgerufen wird. Der Final-Parameter muss beim letzten Aufruf von CryptEncrypt auf TRUE festgelegt werden, damit die Verschlüsselungs-Engine den Verschlüsselungsprozess ordnungsgemäß abschließen kann. Die folgenden zusätzlichen Aktionen werden ausgeführt, wenn FinalAUF TRUE festgelegt ist:
- Wenn es sich bei dem Schlüssel um einen Blockverschlüsselungsschlüssel handelt, werden die Daten auf ein Vielfaches der Blockgröße der Verschlüsselung aufgefüllt. Wenn die Datenlänge der Blockgröße der Verschlüsselung entspricht, wird ein zusätzlicher Auffüllungsblock an die Daten angefügt. Um die Blockgröße einer Verschlüsselung zu ermitteln, verwenden Sie CryptGetKeyParam , um den KP_BLOCKLEN Wert des Schlüssels abzurufen.
- Wenn die Verschlüsselung in einem Verkettungsmodus ausgefü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 Verschlüsselung um eine Datenstromchiffre handelt, setzt die nächste CryptEncrypt die Verschlüsselung in ihren Anfangszustand zurück.
Es gibt keine Möglichkeit, das Feedbackregister der Verschlüsselung auf den KP_IV Wert des Schlüssels festzulegen, ohne den Final-Parameter auf TRUE festzulegen. Wenn dies erforderlich ist, wie in dem Fall, in dem Sie keinen zusätzlichen Auffüllungsblock hinzufügen oder die Größe jedes Blocks ändern möchten, können Sie dies simulieren, indem Sie mithilfe der CryptDuplicateKey-Funktion ein Duplikat des ursprünglichen Schlüssels erstellen und den doppelten Schlüssel an die CryptEncrypt-Funktion übergeben. Dies bewirkt, dass die KP_IV des ursprünglichen Schlüssels im doppelten Schlüssel platziert wird. Nachdem Sie den ursprünglichen Schlüssel erstellt oder importiert haben, können Sie den ursprünglichen Schlüssel nicht mehr 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 öffentlichen RSA-Schlüsseln und die Entschlüsselung mit privaten RSA-Schlüsseln. Die Verschlüsselung verwendet PKCS # 1-Abstand. Bei der Entschlüsselung wird dieser Abstand überprüft. Die Länge der Klartextdaten, 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 ausgewählte Minimum für die PKCS #1-Auffüllung. 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 |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | wincrypt.h |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.dll |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für