using System.ComponentModel;
using System.Runtime.InteropServices;
using Vanara.InteropServices;
namespace Vanara.PInvoke
{
public static partial class AdvApi32
{
/// Contains values to indicate the requested SDDL format.
public enum SDDL_REVISION
{
/// SDDL revision 1.
SDDL_REVISION_1 = 1
}
///
///
/// The ConvertSecurityDescriptorToStringSecurityDescriptor function converts a security descriptor to a string format. You
/// can use the string format to store or transmit the security descriptor.
///
///
/// To convert the string-format security descriptor back to a valid, functional security descriptor, call the
/// ConvertStringSecurityDescriptorToSecurityDescriptor function.
///
///
///
/// A pointer to the security descriptor to convert. The security descriptor can be in absolute or self-relative format.
///
///
/// Specifies the revision level of the output StringSecurityDescriptor string. Currently this value must be SDDL_REVISION_1.
///
///
///
/// Specifies a combination of the SECURITY_INFORMATION bit flags to indicate the components of the security descriptor to include in
/// the output string.
///
///
///
///
/// A pointer to a variable that receives a pointer to a null-terminated security descriptor string. For a description of the
/// string format, see Security Descriptor String Format. To free the returned buffer, call the LocalFree function.
///
///
///
///
/// A pointer to a variable that receives the size, in TCHAR s, of the security descriptor string returned in the
/// StringSecurityDescriptor buffer. This parameter can be NULL if you do not need to retrieve the size. The size represents
/// the size of the buffer in WCHAR s, not the number of WCHAR s in the string.
///
///
///
/// If the function succeeds, the return value is nonzero.
///
/// If the function fails, the return value is zero. To get extended error information, call GetLastError. The GetLastError
/// function may return one of the following error codes.
///
///
///
/// Return code
/// Description
///
/// -
/// ERROR_INVALID_PARAMETER
/// A parameter is not valid.
///
/// -
/// ERROR_UNKNOWN_REVISION
/// The revision level is not valid.
///
/// -
/// ERROR_NONE_MAPPED
/// A security identifier (SID) in the input security descriptor could not be found in an account lookup operation.
///
/// -
/// ERROR_INVALID_ACL
///
/// The access control list (ACL) is not valid. This error is returned if the SE_DACL_PRESENT flag is set in the input security
/// descriptor and the DACL is NULL.
///
///
///
///
///
///
/// If the DACL is NULL, and the SE_DACL_PRESENT control bit is set in the input security descriptor, the function fails.
///
///
/// If the DACL is NULL, and the SE_DACL_PRESENT control bit is not set in the input security descriptor, the resulting
/// security descriptor string does not have a D: component. For more information, see Security Descriptor String Format.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/sddl/nf-sddl-convertsecuritydescriptortostringsecuritydescriptora BOOL
// ConvertSecurityDescriptorToStringSecurityDescriptorA( PSECURITY_DESCRIPTOR SecurityDescriptor, DWORD RequestedStringSDRevision,
// SECURITY_INFORMATION SecurityInformation, LPSTR *StringSecurityDescriptor, PULONG StringSecurityDescriptorLen );
[DllImport(Lib.AdvApi32, SetLastError = true, CharSet = CharSet.Auto)]
[PInvokeData("sddl.h", MSDNShortId = "36140833-8e30-4c32-a88a-c10751b6c223")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool ConvertSecurityDescriptorToStringSecurityDescriptor(PSECURITY_DESCRIPTOR SecurityDescriptor, SDDL_REVISION RequestedStringSDRevision,
SECURITY_INFORMATION SecurityInformation, out SafeLocalHandle StringSecurityDescriptor, out uint StringSecurityDescriptorLen);
///
///
/// The ConvertSecurityDescriptorToStringSecurityDescriptor function converts a security descriptor to a string format. You
/// can use the string format to store or transmit the security descriptor.
///
///
/// To convert the string-format security descriptor back to a valid, functional security descriptor, call the
/// ConvertStringSecurityDescriptorToSecurityDescriptor function.
///
///
///
/// A pointer to the security descriptor to convert. The security descriptor can be in absolute or self-relative format.
///
///
///
/// Specifies a combination of the SECURITY_INFORMATION bit flags to indicate the components of the security descriptor to include in
/// the output string.
///
///
/// A security descriptor string. For a description of the string format, see Security Descriptor String Format.
///
///
/// If the DACL is NULL, and the SE_DACL_PRESENT control bit is set in the input security descriptor, the function fails.
///
///
/// If the DACL is NULL, and the SE_DACL_PRESENT control bit is not set in the input security descriptor, the resulting
/// security descriptor string does not have a D: component. For more information, see Security Descriptor String Format.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/sddl/nf-sddl-convertsecuritydescriptortostringsecuritydescriptora BOOL
// ConvertSecurityDescriptorToStringSecurityDescriptorA( PSECURITY_DESCRIPTOR SecurityDescriptor, DWORD RequestedStringSDRevision,
// SECURITY_INFORMATION SecurityInformation, LPSTR *StringSecurityDescriptor, PULONG StringSecurityDescriptorLen );
[PInvokeData("sddl.h", MSDNShortId = "36140833-8e30-4c32-a88a-c10751b6c223")]
[return: MarshalAs(UnmanagedType.Bool)]
public static string ConvertSecurityDescriptorToStringSecurityDescriptor(PSECURITY_DESCRIPTOR SecurityDescriptor, SECURITY_INFORMATION SecurityInformation)
{
if (!ConvertSecurityDescriptorToStringSecurityDescriptor(SecurityDescriptor, SDDL_REVISION.SDDL_REVISION_1, SecurityInformation, out var sd, out var len))
throw new Win32Exception();
using (sd)
return sd.ToString(-1, CharSet.Auto);
}
///
/// The ConvertSidToStringSid function converts a security identifier (SID) to a string format suitable for display, storage, or transmission.
///
/// A pointer to the SID structure to be converted.
///
/// A pointer to a variable that receives a pointer to a null-terminated SID string. To free the returned buffer, call the LocalFree function.
///
///
/// If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.To get extended error
/// information, call GetLastError.
///
[DllImport(Lib.AdvApi32, CharSet = CharSet.Auto, SetLastError = true, BestFitMapping = false, ThrowOnUnmappableChar = true)]
[return: MarshalAs(UnmanagedType.Bool)]
[PInvokeData("sddl.h", MSDNShortId = "aa376399")]
public static extern bool ConvertSidToStringSid(PSID Sid, out SafeLocalHandle StringSid);
/// Converts a security identifier (SID) to a string format suitable for display, storage, or transmission.
/// The SID structure to be converted.
/// A null-terminated SID string.
[PInvokeData("sddl.h", MSDNShortId = "aa376399")]
public static string ConvertSidToStringSid(PSID Sid)
{
if (!ConvertSidToStringSid(Sid, out var str))
throw new Win32Exception();
using (str)
return str.ToString(-1, CharSet.Auto);
}
///
///
/// The ConvertStringSecurityDescriptorToSecurityDescriptor function converts a string-format security descriptor into a
/// valid, functional security descriptor. This function retrieves a security descriptor that the
/// ConvertSecurityDescriptorToStringSecurityDescriptor function converted to string format.
///
///
///
/// A pointer to a null-terminated string containing the string-format security descriptor to convert.
///
///
/// Specifies the revision level of the StringSecurityDescriptor string. Currently this value must be SDDL_REVISION_1.
///
///
///
/// A pointer to a variable that receives a pointer to the converted security descriptor. The returned security descriptor is
/// self-relative. To free the returned buffer, call the LocalFree function. To convert the security descriptor to an absolute
/// security descriptor, use the MakeAbsoluteSD function.
///
///
///
///
/// A pointer to a variable that receives the size, in bytes, of the converted security descriptor. This parameter can be NULL.
///
///
///
/// If the function succeeds, the return value is nonzero.
///
/// If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may
/// return one of the following error codes.
///
///
///
/// Return code
/// Description
///
/// -
/// ERROR_INVALID_PARAMETER
/// A parameter is not valid.
///
/// -
/// ERROR_UNKNOWN_REVISION
/// The SDDL revision level is not valid.
///
/// -
/// ERROR_NONE_MAPPED
/// A security identifier (SID) in the input security descriptor string could not be found in an account lookup operation.
///
///
///
///
///
/// If ace_type is ACCESS_ALLOWED_OBJECT_ACE_TYPE and neither object_guid nor inherit_object_guid has a GUID
/// specified, then ConvertStringSecurityDescriptorToSecurityDescriptor converts ace_type to ACCESS_ALLOWED_ACE_TYPE.
/// For information about the ace_type, object_guid, and inherit_object_guid fields, see Ace Strings.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/sddl/nf-sddl-convertstringsecuritydescriptortosecuritydescriptora BOOL
// ConvertStringSecurityDescriptorToSecurityDescriptorA( LPCSTR StringSecurityDescriptor, DWORD StringSDRevision,
// PSECURITY_DESCRIPTOR *SecurityDescriptor, PULONG SecurityDescriptorSize );
[DllImport(Lib.AdvApi32, SetLastError = true, CharSet = CharSet.Auto)]
[PInvokeData("sddl.h", MSDNShortId = "c5654148-fb4c-436d-9378-a1168fc82607")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool ConvertStringSecurityDescriptorToSecurityDescriptor(string StringSecurityDescriptor, SDDL_REVISION StringSDRevision, out SafeLocalHandle SecurityDescriptor, out uint SecurityDescriptorSize);
///
///
/// The ConvertStringSecurityDescriptorToSecurityDescriptor function converts a string-format security descriptor into a
/// valid, functional security descriptor. This function retrieves a security descriptor that the
/// ConvertSecurityDescriptorToStringSecurityDescriptor function converted to string format.
///
///
///
/// A pointer to a null-terminated string containing the string-format security descriptor to convert.
///
///
/// A pointer to the converted security descriptor. The returned security descriptor is self-relative. To convert the security
/// descriptor to an absolute security descriptor, use the MakeAbsoluteSD function.
///
///
///
/// If ace_type is ACCESS_ALLOWED_OBJECT_ACE_TYPE and neither object_guid nor inherit_object_guid has a GUID
/// specified, then ConvertStringSecurityDescriptorToSecurityDescriptor converts ace_type to ACCESS_ALLOWED_ACE_TYPE.
/// For information about the ace_type, object_guid, and inherit_object_guid fields, see Ace Strings.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/sddl/nf-sddl-convertstringsecuritydescriptortosecuritydescriptora BOOL
// ConvertStringSecurityDescriptorToSecurityDescriptorA( LPCSTR StringSecurityDescriptor, DWORD StringSDRevision,
// PSECURITY_DESCRIPTOR *SecurityDescriptor, PULONG SecurityDescriptorSize );
[PInvokeData("sddl.h", MSDNShortId = "c5654148-fb4c-436d-9378-a1168fc82607")]
[return: MarshalAs(UnmanagedType.Bool)]
public static SafePSECURITY_DESCRIPTOR ConvertStringSecurityDescriptorToSecurityDescriptor(string StringSecurityDescriptor)
{
if (!ConvertStringSecurityDescriptorToSecurityDescriptor(StringSecurityDescriptor, SDDL_REVISION.SDDL_REVISION_1, out var sd, out var sz))
throw new Win32Exception();
using (sd)
return new SafePSECURITY_DESCRIPTOR(sd.ToArray((int)sz));
}
///
/// The ConvertStringSidToSid function converts a string-format security identifier (SID) into a valid, functional SID. You can use
/// this function to retrieve a SID that the ConvertSidToStringSid function converted to string format.
///
///
/// A pointer to a null-terminated string containing the string-format SID to convert. The SID string can use either the standard
/// S-R-I-S-S… format for SID strings, or the SID string constant format, such as "BA" for built-in administrators. For more
/// information about SID string notation, see SID Components.
///
///
/// A pointer to a variable that receives a pointer to the converted SID. To free the returned buffer, call the LocalFree function.
///
///
/// If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error
/// information, call GetLastError.
///
[DllImport(Lib.AdvApi32, CharSet = CharSet.Auto, SetLastError = true, BestFitMapping = false, ThrowOnUnmappableChar = true)]
[return: MarshalAs(UnmanagedType.Bool)]
[PInvokeData("sddl.h", MSDNShortId = "aa376402")]
public static extern bool ConvertStringSidToSid(string pStringSid, out SafeLocalHandle sid);
///
/// The ConvertStringSidToSid function converts a string-format security identifier (SID) into a valid, functional SID. You can use
/// this function to retrieve a SID that the ConvertSidToStringSid function converted to string format.
///
///
/// A pointer to a null-terminated string containing the string-format SID to convert. The SID string can use either the standard
/// S-R-I-S-S… format for SID strings, or the SID string constant format, such as "BA" for built-in administrators. For more
/// information about SID string notation, see SID Components.
///
/// A pointer to the converted SID.
[PInvokeData("sddl.h", MSDNShortId = "aa376402")]
[return: MarshalAs(UnmanagedType.Bool)]
public static SafePSID ConvertStringSidToSid(string pStringSid)
{
if (!ConvertStringSidToSid(pStringSid, out var psid))
throw new Win32Exception();
using (psid)
return new SafePSID(psid.DangerousGetHandle());
}
}
}