Funzione CryptUpdateProtectedState (dpapi.h)

Articolo
08/23/2023

La funzione CryptUpdateProtectedState esegue la migrazione delle chiavi master dell'utente corrente dopo la modifica dell'identificatore di sicurezza dell'utente. Questa funzione può essere usata per conservare i dati crittografati dopo che un utente è stato spostato da un dominio a un altro.

Sintassi

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

Parametri

[in] pOldSid

Indirizzo di una struttura SID contenente il SID precedente dell'utente. Questo SID viene usato per individuare le chiavi master precedenti. Se questo parametro è NULL, vengono migrate le chiavi master per il SID utente corrente.

Questo parametro o il parametro pwszOldPassword può essere NULL, ma non entrambi.

[in] pwszOldPassword

Puntatore a una stringa Unicode con terminazione null contenente la password dell'utente prima della modifica del SID. Questa password viene usata per decrittografare le chiavi master precedenti. Se questo parametro è NULL, verrà usata la password dell'utente corrente.

Questo parametro o il parametro pOldSid può essere NULL, ma non entrambi.

[in] dwFlags

Non usato. Deve essere zero.

[out] pdwSuccessCount

Indirizzo di una variabile DWORD che riceve il numero di chiavi master migrate correttamente.

[out] pdwFailureCount

Indirizzo di una variabile DWORD che riceve il numero di chiavi master che non è stato possibile decrittografare.

Non è necessariamente un errore se non è possibile decrittografare una o più chiavi master. Alcuni utenti possono avere chiavi master che sono stagnanti e non potevano essere state decrittografate per molto tempo. Un modo in cui ciò può verificarsi è quando la password di un utente locale è stata reimpostata in modo amministrativo.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è TRUE.

Se la funzione ha esito negativo, il valore restituito è FALSE. Per informazioni sull'errore estese, chiamare GetLastError. Alcuni possibili codici di errore includono quanto segue.

Codice restituito	Descrizione
ERROR_INVALID_PARAMETER	Uno dei parametri contiene un valore non valido.
ERROR_OUTOFMEMORY	Si è verificato un errore di allocazione della memoria.
ERROR_ENCRYPTION_FAILED	Impossibile crittografare la password precedente.

Commenti

Questa funzione decrittografa tutte le chiavi master dell'utente nella vecchia directory della chiave master, usando la password precedente e le archivia nella directory della chiave master corrente dell'utente, crittografata con la password corrente dell'utente.

Questa funzione deve essere chiamata dall'account utente a cui vengono migrate le chiavi.

Se questa funzione è in grado di eseguire correttamente la migrazione di una chiave master precedente, eliminerà automaticamente la chiave master precedente. Le chiavi master che non possono essere decrittografate non vengono eliminate.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	dpapi.h
Libreria	Crypt32.lib
DLL	Crypt32.dll