Funzione SetNamedSecurityInfoA (aclapi.h)

Articolo
11/20/2024

La funzione SetNamedSecurityInfo imposta le informazioni di sicurezza specificate nel descrittore di sicurezza di un oggetto specificato. Il chiamante identifica l'oggetto in base al nome.

Sintassi

DWORD SetNamedSecurityInfoA(
  [in]           LPSTR                pObjectName,
  [in]           SE_OBJECT_TYPE       ObjectType,
  [in]           SECURITY_INFORMATION SecurityInfo,
  [in, optional] PSID                 psidOwner,
  [in, optional] PSID                 psidGroup,
  [in, optional] PACL                 pDacl,
  [in, optional] PACL                 pSacl
);

Parametri

[in] pObjectName

Puntatore a un nullstringa con terminazione che specifica il nome dell'oggetto per cui impostare le informazioni di sicurezza. Può trattarsi del nome di un file o di una directory locale o remota in un file system NTFS, una condivisione di rete, una chiave del Registro di sistema, un semaforo, un evento, un mutex, un mapping di file o un timer in attesa.

Per le descrizioni dei formati stringa per i diversi tipi di oggetto, vedere SE_OBJECT_TYPE.

[in] ObjectType

Valore dell'enumerazione SE_OBJECT_TYPE che indica il tipo di oggetto denominato dal parametro pObjectName.

[in] SecurityInfo

Set di flag di bit che indicano il tipo di informazioni di sicurezza da impostare. Questo parametro può essere una combinazione dei flag di bit SECURITY_INFORMATION.

[in, optional] psidOwner

Puntatore a una struttura SID che identifica il proprietario dell'oggetto. Se il chiamante non dispone della costante SeRestorePrivilege (vedere Costanti privilegio), questo SID deve essere contenuto nel token del chiamante e deve disporre dell'autorizzazione SE_GROUP_OWNER abilitata. Il parametro SecurityInfo deve includere il flag di OWNER_SECURITY_INFORMATION. Per impostare il proprietario, il chiamante deve avere WRITE_OWNER accesso all'oggetto o disporre del privilegio SE_TAKE_OWNERSHIP_NAME abilitato. Se non si imposta il proprietario SID, questo parametro può essere NULL.

[in, optional] psidGroup

Puntatore a un SID che identifica il gruppo primario dell'oggetto. Il parametro SecurityInfo deve includere il flag di GROUP_SECURITY_INFORMATION. Se non si imposta il SID del gruppo primario, questo parametro può essere NULL.

[in, optional] pDacl

Puntatore al nuovo DACL per l'oggetto. Il parametro SecurityInfo deve includere il flag di DACL_SECURITY_INFORMATION. Il chiamante deve avere WRITE_DAC accesso all'oggetto o essere il proprietario dell'oggetto. Se non si imposta il DACL, questo parametro può essere NULL.

[in, optional] pSacl

Puntatore al nuovo sacl per l'oggetto . Il parametro SecurityInfo deve includere uno dei flag seguenti: SACL_SECURITY_INFORMATION, LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION, SCOPE_SECURITY_INFORMATION o BACKUP_SECURITY_INFORMATION.

Se si imposta SACL_SECURITY_INFORMATION o SCOPE_SECURITY_INFORMATION, il chiamante deve avere il privilegio di SE_SECURITY_NAME abilitato. Se non si imposta SACL, questo parametro può essere NULL.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce ERROR_SUCCESS.

Se la funzione ha esito negativo, restituisce un codice di errore diverso da zero definito in WinError.h.

Osservazioni

Se si imposta l'elenco di controllo di accesso discrezionale (DACL) o qualsiasi elemento nell'elenco di controllo di accesso del sistema (SACL) di un oggetto, il sistema propaga automaticamente eventuali voci ereditabili di controllo di accesso (ACL) a oggetti figlio esistenti, in base alle regole di ereditarietà.

È possibile usare la funzione SetNamedSecurityInfo con i tipi di oggetti seguenti:

File o directory locali o remoti in un file NTFS
Stampanti locali o remote
Servizi Windows locali o remoti
Condivisioni di rete
Chiavi del Registro di sistema
Semafori, eventi, mutex e timer waitable
Oggetti di mapping di file
Oggetti servizio directory

La funzione SetNamedSecurityInfo non riordina gli ACL consentiti o negati dall'accesso in base all'ordine preferito. Quando si propagano gli ACL ereditabili a oggetti figlio esistenti, SetNamedSecurityInfo inserisce gli ACL ereditati in ordine dopo tutti gli ACL non inriti negli elenchi di controllo di accesso degli oggetti figlio.

Questa funzione trasferisce informazioni in testo non crittografato. Le informazioni trasferite da questa funzione vengono firmate a meno che la firma non sia stata disattivata per il sistema, ma non viene eseguita alcuna crittografia.

Quando si aggiornano i diritti di accesso di una cartella indicata da un percorso UNC, ad esempio \Test\TestFolder, l'ace ereditato originale viene rimosso e il percorso completo del volume non è incluso.

Esempi

Per un esempio che usa questa funzione, vedere Modifica degli elenchi di controllo di accesso di un oggetto o acquisizione della proprietà dell'oggetto.

Nota

L'intestazione aclapi.h definisce SetNamedSecurityInfo come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [app desktop \| App UWP]
server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	aclapi.h
libreria	Advapi32.lib
dll	Advapi32.dll