CryptUpdateProtectedState-Funktion (dpapi.h)

Artikel
08/23/2023

Die CryptUpdateProtectedState-Funktion migriert die master Schlüssel des aktuellen Benutzers, nachdem sich die Sicherheits-ID (SID) des Benutzers geändert hat. Diese Funktion kann verwendet werden, um verschlüsselte Daten beizubehalten, nachdem ein Benutzer von einer Domäne in eine andere verschoben wurde.

Syntax

DPAPI_IMP BOOL CryptUpdateProtectedState(
  [in]  PSID    pOldSid,
  [in]  LPCWSTR pwszOldPassword,
  [in]  DWORD   dwFlags,
  [out] DWORD   *pdwSuccessCount,
  [out] DWORD   *pdwFailureCount
);

Parameter

[in] pOldSid

Die Adresse einer SID-Struktur , die die vorherige SID des Benutzers enthält. Diese SID wird verwendet, um die alten master Schlüssel zu suchen. Wenn dieser Parameter NULL ist, werden die master Schlüssel für die aktuelle Benutzer-SID migriert.

Entweder dieser Parameter oder der pwszOldPassword-Parameter kann NULL sein, aber nicht beide.

[in] pwszOldPassword

Ein Zeiger auf eine Unicode-Zeichenfolge mit NULL-Beendigung, die das Kennwort des Benutzers enthält, bevor die SID geändert wurde. Dieses Kennwort wird verwendet, um die alten master Schlüssel zu entschlüsseln. Wenn dieser Parameter NULL ist, wird das Kennwort des aktuellen Benutzers verwendet.

Entweder dieser Parameter oder der pOldSid-Parameter kann NULL sein, aber nicht beide.

[in] dwFlags

Wird nicht verwendet. Muss Null sein.

[out] pdwSuccessCount

Die Adresse einer DWORD-Variablen, die die Anzahl der master Schlüssel empfängt, die erfolgreich migriert wurden.

[out] pdwFailureCount

Die Adresse einer DWORD-Variablen, die die Anzahl der master Schlüssel empfängt, die nicht entschlüsselt werden konnten.

Es ist nicht unbedingt ein Fehler, wenn ein oder mehrere master Schlüssel nicht entschlüsselt werden können. Einige Benutzer besitzen möglicherweise master Schlüssel, die stagnieren und lange Zeit nicht entschlüsselt werden konnten. Dies kann unter anderem passieren, wenn das Kennwort eines lokalen Benutzers administrativ zurückgesetzt wurde.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert TRUE.

Wenn die Funktion fehlschlägt, ist der Rückgabewert FALSE. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten. Einige mögliche Fehlercodes sind die folgenden:

Rückgabecode	Beschreibung
ERROR_INVALID_PARAMETER	Einer der Parameter enthält einen ungültigen Wert.
ERROR_OUTOFMEMORY	Ein Speicherbelegungsfehler ist aufgetreten.
ERROR_ENCRYPTION_FAILED	Das alte Kennwort konnte nicht verschlüsselt werden.

Hinweise

Diese Funktion entschlüsselt alle master Schlüssel des Benutzers im alten schlüsselverzeichnis master unter Verwendung des vorherigen Kennworts und speichert sie im aktuellen schlüsselverzeichnis des Benutzers master, verschlüsselt mit dem aktuellen Kennwort des Benutzers.

Diese Funktion muss aus dem Benutzerkonto aufgerufen werden, zu dem die Schlüssel migriert werden.

Wenn diese Funktion einen alten master Schlüssel erfolgreich migrieren kann, wird der alte master Schlüssel automatisch gelöscht. Hauptschlüssel, die nicht entschlüsselt werden können, werden nicht gelöscht.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	dpapi.h
Bibliothek	Crypt32.lib
DLL	Crypt32.dll

Share via