diff --git a/NSspi/Contexts/SafeContextHandle.cs b/NSspi/Contexts/SafeContextHandle.cs index 76fde01..93de738 100644 --- a/NSspi/Contexts/SafeContextHandle.cs +++ b/NSspi/Contexts/SafeContextHandle.cs @@ -8,10 +8,17 @@ namespace NSspi.Contexts /// public class SafeContextHandle : SafeSspiHandle { + /// + /// Initializes a new instance of the class. + /// public SafeContextHandle() : base() { } + /// + /// Releases the safe context handle. + /// + /// [ReliabilityContract( Consistency.WillNotCorruptState, Cer.Success )] protected override bool ReleaseHandle() { diff --git a/NSspi/Credentials/Credential.cs b/NSspi/Credentials/Credential.cs index 4938a4d..ae8b101 100644 --- a/NSspi/Credentials/Credential.cs +++ b/NSspi/Credentials/Credential.cs @@ -9,16 +9,16 @@ namespace NSspi.Credentials /// public class Credential : IDisposable { + /// + /// The name of the security package that controls the credential. + /// + private readonly string securityPackage; + /// /// Whether the Credential has been disposed. /// private bool disposed; - /// - /// The name of the security package that controls the credential. - /// - private string securityPackage; - /// /// A safe handle to the credential's handle. /// @@ -35,11 +35,10 @@ namespace NSspi.Credentials /// The security package to acquire the credential from. public Credential( string package ) { - this.disposed = false; this.securityPackage = package; + this.disposed = false; this.expiry = DateTime.MinValue; - this.PackageInfo = PackageSupport.GetPackageCapabilities( this.SecurityPackage ); } @@ -178,6 +177,10 @@ namespace NSspi.Credentials GC.SuppressFinalize( this ); } + /// + /// Releases all resources associted with the credential. + /// + /// protected virtual void Dispose( bool disposing ) { if( this.disposed == false ) diff --git a/NSspi/Credentials/SafeCredentialHandle.cs b/NSspi/Credentials/SafeCredentialHandle.cs index 7c2ce16..7d90e23 100644 --- a/NSspi/Credentials/SafeCredentialHandle.cs +++ b/NSspi/Credentials/SafeCredentialHandle.cs @@ -8,10 +8,17 @@ namespace NSspi.Credentials /// public class SafeCredentialHandle : SafeSspiHandle { + /// + /// Initializes a new instance of the class. + /// public SafeCredentialHandle() : base() { } + /// + /// Releases the resources held by the credential handle. + /// + /// [ReliabilityContract( Consistency.WillNotCorruptState, Cer.Success )] protected override bool ReleaseHandle() { diff --git a/NSspi/EnumMgr.cs b/NSspi/EnumMgr.cs index 27189e3..d55d74a 100644 --- a/NSspi/EnumMgr.cs +++ b/NSspi/EnumMgr.cs @@ -3,19 +3,38 @@ using System.Reflection; namespace NSspi { + /// + /// Tags an enumeration member with a string that can be programmatically accessed. + /// [AttributeUsage( AttributeTargets.Field )] public class EnumStringAttribute : Attribute { + /// + /// Initializes a new instance of the class. + /// + /// The string to associate with the enumeration member. public EnumStringAttribute( string text ) { this.Text = text; } + /// + /// Gets the string associated with the enumeration member. + /// public string Text { get; private set; } } + /// + /// Converts betwen enumeration members and the strings associated to the members through the + /// type. + /// public class EnumMgr { + /// + /// Gets the text associated with the given enumeration member through a . + /// + /// + /// public static string ToText( Enum value ) { FieldInfo field = value.GetType().GetField( value.ToString() ); @@ -32,6 +51,12 @@ namespace NSspi } } + /// + /// Returns the enumeration member that is tagged with the given text using the type. + /// + /// The enumeration type to inspect. + /// + /// public static T FromText( string text ) { FieldInfo[] fields = typeof( T ).GetFields(); diff --git a/NSspi/SecurityStatus.cs b/NSspi/SecurityStatus.cs index 1cd3a09..cf6ecd9 100644 --- a/NSspi/SecurityStatus.cs +++ b/NSspi/SecurityStatus.cs @@ -56,26 +56,48 @@ namespace NSspi [EnumString( "The security context was used after its expiration time passed." )] ContextExpired = 0x00090317, + /// + /// The credentials supplied to the security context were not fully initialized. + /// [EnumString( "The credentials supplied to the security context were not fully initialized." )] CredentialsNeeded = 0x00090320, - [EnumString( "The context data must be re-negotiated with the peer" )] + /// + /// The context data must be re-negotiated with the peer. + /// + [EnumString( "The context data must be re-negotiated with the peer." )] Renegotiate = 0x00090321, - // Errors + // -------------- Errors -------------- + + /// + /// The SSPI operation failed due to insufficient memory resources. + /// [EnumString( "Not enough memory." )] OutOfMemory = 0x80090300, + /// + /// The handle provided to the API was invalid. + /// [EnumString( "The handle provided to the API was invalid." )] InvalidHandle = 0x80090301, - [EnumString( "The attempted operation is not supported" )] + /// + /// The attempted operation is not supported. + /// + [EnumString( "The attempted operation is not supported." )] Unsupported = 0x80090302, + /// + /// The specified principle is not known in the authentication system. + /// [EnumString( "The specified principle is not known in the authentication system." )] TargetUnknown = 0x80090303, - [EnumString( "An internal error occurred" )] + /// + /// An internal error occurred + /// + [EnumString( "An internal error occurred." )] InternalError = 0x80090304, /// @@ -84,7 +106,16 @@ namespace NSspi [EnumString( "The requested security package was not found." )] PackageNotFound = 0x80090305, + /// + /// Cannot use the provided credentials, the caller is not the owner of the credentials. + /// + [EnumString( "The caller is not the owner of the desired credentials." )] NotOwner = 0x80090306, + + /// + /// The requested security package failed to initalize, and thus cannot be used. + /// + [EnumString( "The requested security package failed to initalize, and thus cannot be used." )] CannotInstall = 0x80090307, /// @@ -93,7 +124,16 @@ namespace NSspi [EnumString( "The provided authentication token is invalid or corrupted." )] InvalidToken = 0x80090308, + /// + /// The security package is not able to marshall the logon buffer, so the logon attempt has failed + /// + [EnumString( "The security package is not able to marshall the logon buffer, so the logon attempt has failed." )] CannotPack = 0x80090309, + + /// + /// The per-message Quality of Protection is not supported by the security package. + /// + [EnumString( "The per-message Quality of Protection is not supported by the security package." )] QopNotSupported = 0x8009030A, /// @@ -102,22 +142,41 @@ namespace NSspi [EnumString( "Impersonation is not supported with the current security package." )] NoImpersonation = 0x8009030B, + /// + /// The logon was denied, perhaps because the provided credentials were incorrect. + /// [EnumString( "The logon was denied, perhaps because the provided credentials were incorrect." )] LogonDenied = 0x8009030C, + /// + /// The credentials provided are not recognized by the selected security package. + /// [EnumString( "The credentials provided are not recognized by the selected security package." )] UnknownCredentials = 0x8009030D, + /// + /// No credentials are available in the selected security package. + /// [EnumString( "No credentials are available in the selected security package." )] NoCredentials = 0x8009030E, + /// + /// A message that was provided to the Decrypt or VerifySignature functions was altered after + /// it was created. + /// [EnumString( "A message that was provided to the Decrypt or VerifySignature functions was altered " + - "after it was created." )] + "after it was created." )] MessageAltered = 0x8009030F, + /// + /// A message was received out of the expected order. + /// [EnumString( "A message was received out of the expected order." )] OutOfSequence = 0x80090310, + /// + /// The current security package cannot contact an authenticating authority. + /// [EnumString( "The current security package cannot contact an authenticating authority." )] NoAuthenticatingAuthority = 0x80090311, @@ -132,20 +191,87 @@ namespace NSspi /// will indicate success, but will save off the extra, unrelated data in a buffer of /// type 'extra'. /// + [EnumString( "The buffer provided to an SSPI API call contained a message that was not complete." )] IncompleteMessage = 0x80090318, + /// + /// The credentials supplied were not complete, and could not be verified. The context could not be initialized. + /// + [EnumString( "The credentials supplied were not complete, and could not be verified. The context could not be initialized." )] IncompleteCredentials = 0x80090320, + + /// + /// The buffers supplied to a security function were too small. + /// + [EnumString( "The buffers supplied to a security function were too small." )] BufferNotEnough = 0x80090321, + + /// + /// The target principal name is incorrect. + /// + [EnumString( "The target principal name is incorrect." )] WrongPrincipal = 0x80090322, + + /// + /// The clocks on the client and server machines are skewed. + /// + [EnumString( "The clocks on the client and server machines are skewed." )] TimeSkew = 0x80090324, + + /// + /// The certificate chain was issued by an authority that is not trusted. + /// + [EnumString( "The certificate chain was issued by an authority that is not trusted." )] UntrustedRoot = 0x80090325, + + /// + /// The message received was unexpected or badly formatted. + /// + [EnumString( "The message received was unexpected or badly formatted." )] IllegalMessage = 0x80090326, + + /// + /// An unknown error occurred while processing the certificate. + /// + [EnumString( "An unknown error occurred while processing the certificate." )] CertUnknown = 0x80090327, + + /// + /// The received certificate has expired. + /// + [EnumString( "The received certificate has expired." )] CertExpired = 0x80090328, + + /// + /// The client and server cannot communicate, because they do not possess a common algorithm. + /// + [EnumString( "The client and server cannot communicate, because they do not possess a common algorithm." )] AlgorithmMismatch = 0x80090331, + + /// + /// The security context could not be established due to a failure in the requested quality + /// of service (e.g. mutual authentication or delegation). + /// + [EnumString( "The security context could not be established due to a failure in the requested " + + "quality of service (e.g. mutual authentication or delegation)." )] SecurityQosFailed = 0x80090332, + + /// + /// Smartcard logon is required and was not used. + /// + [EnumString( "Smartcard logon is required and was not used." )] SmartcardLogonRequired = 0x8009033E, + + /// + /// An unsupported preauthentication mechanism was presented to the Kerberos package. + /// + [EnumString( "An unsupported preauthentication mechanism was presented to the Kerberos package." )] UnsupportedPreauth = 0x80090343, + + /// + /// Client's supplied SSPI channel bindings were incorrect. + /// + [EnumString( "Client's supplied SSPI channel bindings were incorrect." )] BadBinding = 0x80090346 } diff --git a/NSspi/SspiHandle.cs b/NSspi/SspiHandle.cs index a5dfb0c..127563a 100644 --- a/NSspi/SspiHandle.cs +++ b/NSspi/SspiHandle.cs @@ -55,17 +55,27 @@ namespace NSspi { internal RawSspiHandle rawHandle; + /// + /// Initializes a new instance of the class. + /// protected SafeSspiHandle() : base( IntPtr.Zero, true ) { this.rawHandle = new RawSspiHandle(); } + /// + /// Gets whether the handle is invalid. + /// public override bool IsInvalid { get { return IsClosed || this.rawHandle.IsZero(); } } + /// + /// Marks the handle as no longer being in use. + /// + /// [ReliabilityContract( Consistency.WillNotCorruptState, Cer.Success )] protected override bool ReleaseHandle() { diff --git a/NSspi/TimeStamp.cs b/NSspi/TimeStamp.cs index 3f44dc4..2c248a5 100644 --- a/NSspi/TimeStamp.cs +++ b/NSspi/TimeStamp.cs @@ -10,6 +10,9 @@ namespace NSspi [StructLayout( LayoutKind.Sequential )] public struct TimeStamp { + /// + /// Returns the calendar date and time corresponding a zero timestamp. + /// public static readonly DateTime Epoch = new DateTime( 1601, 1, 1, 0, 0, 0, DateTimeKind.Utc ); ///