From 76849b7f6f6553edbff1c024b5d0cbb21cdfb2b9 Mon Sep 17 00:00:00 2001 From: David Hall Date: Tue, 5 Nov 2019 16:20:52 -0700 Subject: [PATCH] Added documentation --- Security/AccessControl/Claims.cs | 185 +++++++++++++++++---------------------- 1 file changed, 78 insertions(+), 107 deletions(-) diff --git a/Security/AccessControl/Claims.cs b/Security/AccessControl/Claims.cs index 151b1388..fe752c09 100644 --- a/Security/AccessControl/Claims.cs +++ b/Security/AccessControl/Claims.cs @@ -5,8 +5,6 @@ using System.Runtime.Serialization; using Vanara.PInvoke; using static Vanara.PInvoke.Authz; -// ReSharper disable InconsistentNaming - namespace Microsoft.Samples.DynamicAccessControl { /// Enumeration used to identify if a ClaimValueDictionary comprised of user or device claims. @@ -20,59 +18,77 @@ namespace Microsoft.Samples.DynamicAccessControl [Serializable] public class BadValueException : Exception { - public BadValueException() { } + /// Initializes a new instance of the class. + public BadValueException() + { + } - public BadValueException(string message) : base(message) { } + /// Initializes a new instance of the class. + /// The message that describes the error. + public BadValueException(string message) : base(message) + { + } - public BadValueException(string message, Exception innerException) : base(message, innerException) { } + /// Initializes a new instance of the class. + /// The error message that explains the reason for the exception. + /// + /// The exception that is the cause of the current exception, or a null reference (Nothing in Visual Basic) if no inner exception is specified. + /// + public BadValueException(string message, Exception innerException) : base(message, innerException) + { + } - protected BadValueException(SerializationInfo info, StreamingContext context) : base(info, context) { } + /// Initializes a new instance of the class. + /// + /// The that holds the serialized object data about the exception + /// being thrown. + /// + /// + /// The that contains contextual information about the source or destination. + /// + protected BadValueException(SerializationInfo info, StreamingContext context) : base(info, context) + { + } } /// - /// Class to represent the type of claims values held, the value(s) and obtain native (unmanaged) pointers to the value as they are stored in the union - /// members of AUTHZ_SECURITY_ATTRIBUTE_V1 structure's 'Values' field. + /// Class to represent the type of claims values held, the value(s) and obtain native (unmanaged) pointers to the value as they are + /// stored in the union members of AUTHZ_SECURITY_ATTRIBUTE_V1 structure's 'Values' field. /// public class ClaimValue { internal AUTHZ_SECURITY_ATTRIBUTE_V1 attr; - public ClaimValue(string value) - { - attr = new AUTHZ_SECURITY_ATTRIBUTE_V1(null, value); - } + /// Initializes a new instance of the class based on a string. + /// The string value. + public ClaimValue(string value) => attr = new AUTHZ_SECURITY_ATTRIBUTE_V1(null, value); - public ClaimValue(ulong version, string fullyQualifiedBinaryName) - { - attr = new AUTHZ_SECURITY_ATTRIBUTE_V1(null, new AUTHZ_SECURITY_ATTRIBUTE_FQBN_VALUE { pName = fullyQualifiedBinaryName, Version = version }); - } + /// Initializes a new instance of the class based on a fully qualified binary name and version. + /// The version. + /// Name of the fully qualified binary. + public ClaimValue(ulong version, string fullyQualifiedBinaryName) => attr = new AUTHZ_SECURITY_ATTRIBUTE_V1(null, new AUTHZ_SECURITY_ATTRIBUTE_FQBN_VALUE { pName = fullyQualifiedBinaryName, Version = version }); - public ClaimValue(string[] value) - { - attr = new AUTHZ_SECURITY_ATTRIBUTE_V1(null, value); - } + /// Initializes a new instance of the class based on multiple string values. + /// The string values. + public ClaimValue(string[] value) => attr = new AUTHZ_SECURITY_ATTRIBUTE_V1(null, value); - public ClaimValue(byte[] value) - { - attr = new AUTHZ_SECURITY_ATTRIBUTE_V1(null, new AUTHZ_SECURITY_ATTRIBUTE_OCTET_STRING_VALUE { pValue = value, ValueLength = (uint)value.Length }); - } + /// Initializes a new instance of the class based on a binary blob. + /// The value. + public ClaimValue(byte[] value) => attr = new AUTHZ_SECURITY_ATTRIBUTE_V1(null, new AUTHZ_SECURITY_ATTRIBUTE_OCTET_STRING_VALUE { pValue = value, ValueLength = (uint)value.Length }); - public ClaimValue(ulong value) - { - attr = new AUTHZ_SECURITY_ATTRIBUTE_V1(null, value); - } + /// Initializes a new instance of the class based on an unsigned long value. + /// The value. + public ClaimValue(ulong value) => attr = new AUTHZ_SECURITY_ATTRIBUTE_V1(null, value); - public ClaimValue(long value) - { - attr = new AUTHZ_SECURITY_ATTRIBUTE_V1(null, value); - } + /// Initializes a new instance of the class based on a long value. + /// The value. + public ClaimValue(long value) => attr = new AUTHZ_SECURITY_ATTRIBUTE_V1(null, value); - public ClaimValue(bool value) - { - attr = new AUTHZ_SECURITY_ATTRIBUTE_V1(null, value); - } + /// Initializes a new instance of the class based on a boolean value. + /// if set to [value]. + public ClaimValue(bool value) => attr = new AUTHZ_SECURITY_ATTRIBUTE_V1(null, value); - /// Get the number of values contained in the Microsoft.Samples.Cbac.ClaimValue + /// Get the number of values contained in the object. public uint ValueCount => attr.ValueCount; } @@ -85,14 +101,19 @@ namespace Microsoft.Samples.DynamicAccessControl /// Identifies if this instance represents user's claims or device's claims /// ClaimDefinitionType.User to indicate user's claims and ClaimDefinitionType.Device to indicate device's claims. /// - /// When ClaimDefinitionType.User, AithzModifyClaims in invoked with SidClass AuthzContextInfoUserClaims and when ClaimDefinitionType.Device with - /// SidClass AuthzContextInfoDeviceClaims. + /// When ClaimDefinitionType.User, AithzModifyClaims in invoked with SidClass AuthzContextInfoUserClaims and when + /// ClaimDefinitionType.Device with SidClass AuthzContextInfoDeviceClaims. /// - public ClaimValueDictionary(ClaimDefinitionType type) - { - claimDefnType = type; - } + public ClaimValueDictionary(ClaimDefinitionType type) => claimDefnType = type; + /// Initializes a new instance of the class. + /// + /// A object containing the information required to serialize the . + /// + /// + /// A structure containing the source and destination of the + /// serialized stream associated with the . + /// protected ClaimValueDictionary(SerializationInfo info, StreamingContext context) : base(info, context) { @@ -100,8 +121,8 @@ namespace Microsoft.Samples.DynamicAccessControl /// Adds or replaces claims in the specified Authz Client Context. /// - /// This method invokes AuthzModifyClaims, modifying the claims using AUTHZ_SECURITY_ATTRIBUTE_OPERATION_REPLACE. This ensures that the values of a - /// claims that already exists are replaces and the ones not present are added. + /// This method invokes AuthzModifyClaims, modifying the claims using AUTHZ_SECURITY_ATTRIBUTE_OPERATION_REPLACE. This ensures that + /// the values of a claims that already exists are replaces and the ones not present are added. /// /// Handle to the Authz Client Context to be modified /// Win32Error.ERROR_SUCCESS on success and Win32 error code otherwise. @@ -134,6 +155,18 @@ namespace Microsoft.Samples.DynamicAccessControl return Win32Error.ERROR_SUCCESS; } + /// + /// Implements the interface and returns the data needed to serialize the + /// instance. + /// + /// + /// A object that contains the information required to serialize the + /// instance. + /// + /// + /// A structure that contains the source and destination of the + /// serialized stream associated with the instance. + /// public override void GetObjectData(SerializationInfo info, StreamingContext context) { base.GetObjectData(info, context); @@ -143,67 +176,5 @@ namespace Microsoft.Samples.DynamicAccessControl info.AddValue("claimDefnType", claimDefnType); } } - - /*static class - { - [StructLayout(LayoutKind.Sequential)] - public struct AUTHZ_SECURITY_ATTRIBUTES_INFORMATION - { - public USHORT Version; - public USHORT Reserved; - public uint AttributeCount; - public PAUTHZ_SECURITY_ATTRIBUTE_V1 pAttributeV1; - } - - public enum AuthzSecurityAttributeValueType : ushort - { - Invalid = 0x0, - Int = 0x1, - String = 0x3, - Boolean = 0x6, - } - - [Flags] - public enum AuthzSecurityAttributeFlags : uint // uint - { - None = 0x0, - NonInheritable = 0x1, - ValueCaseSensitive = 0x2, - } - - [StructLayout(LayoutKind.Sequential)] - public struct AUTHZ_SECURITY_ATTRIBUTE_V1 - { - [MarshalAs(UnmanagedType.LPWStr)] public string Name; - public AuthzSecurityAttributeValueType Type; - public USHORT Reserved; - public AuthzSecurityAttributeFlags Flags; - public uint ValueCount; - public IntPtr Values; - } - - public enum AuthzContextInformationClass : uint - { - AuthzContextInfoUserClaims = 13, - AuthzContextInfoDeviceClaims, - }; - - public enum AuthzSecurityAttributeOperation : uint - { - None = 0, - ReplaceAll, - Add, - Delete, - Replace - } - - [DllImport(Win32.AUTHZ_DLL, CharSet = CharSet.Unicode, SetLastError = true)] - [return: MarshalAs(UnmanagedType.Bool)] - public static extern bool AuthzModifyClaims( - AUTHZ_CLIENT_CONTEXT_HANDLE handleClientContext, - AuthzContextInformationClass infoClass, - AuthzSecurityAttributeOperation[] claimOperation, - ref AUTHZ_SECURITY_ATTRIBUTES_INFORMATION claims); - }*/ } } \ No newline at end of file