diff --git a/src/Microsoft.IdentityModel.Tokens/AsymmetricSecurityKey.cs b/src/Microsoft.IdentityModel.Tokens/AsymmetricSecurityKey.cs index 708df36b2c..87000a0e49 100644 --- a/src/Microsoft.IdentityModel.Tokens/AsymmetricSecurityKey.cs +++ b/src/Microsoft.IdentityModel.Tokens/AsymmetricSecurityKey.cs @@ -28,9 +28,13 @@ internal AsymmetricSecurityKey(SecurityKey key) public abstract bool HasPrivateKey { get; } /// - /// Gets the status of the private key. + /// Gets a value indicating the existence of the private key. /// - /// if private key exists for sure; if private key doesn't exist for sure; if we cannot determine. + /// + /// if the private key exists. + /// if the private key does not exist. + /// if the existence of the private key cannot be determined. + /// public abstract PrivateKeyStatus PrivateKeyStatus { get; } } diff --git a/src/Microsoft.IdentityModel.Tokens/AsymmetricSignatureProvider.cs b/src/Microsoft.IdentityModel.Tokens/AsymmetricSignatureProvider.cs index 6183e64781..5cd493f1ae 100644 --- a/src/Microsoft.IdentityModel.Tokens/AsymmetricSignatureProvider.cs +++ b/src/Microsoft.IdentityModel.Tokens/AsymmetricSignatureProvider.cs @@ -293,8 +293,8 @@ public override byte[] Sign(byte[] input, int offset, int count) /// Validates that an asymmetric key size is of sufficient size for a SignatureAlgorithm. /// /// The asymmetric key to validate. - /// Algorithm for which this key will be used. - /// Whether they key will be used for creating signatures. + /// The algorithm for which this key will be used. + /// If true, the provider will be used for creating signatures. /// Thrown if is null. /// Thrown if is null or empty. /// Thrown if is less than the minimum acceptable size. diff --git a/src/Microsoft.IdentityModel.Tokens/CompressionProviderFactory.cs b/src/Microsoft.IdentityModel.Tokens/CompressionProviderFactory.cs index cec29c53de..cf230ff037 100644 --- a/src/Microsoft.IdentityModel.Tokens/CompressionProviderFactory.cs +++ b/src/Microsoft.IdentityModel.Tokens/CompressionProviderFactory.cs @@ -55,10 +55,10 @@ public static CompressionProviderFactory Default public ICompressionProvider CustomCompressionProvider { get; set; } /// - /// Checks if the specified cryptographic algorithm is supported. + /// Determines whether the specified algorithm is supported. /// /// The name of the cryptographic algorithm. - /// True if the algorithm is supported; otherwise, false. + /// if the algorithm is supported; otherwise, . public virtual bool IsSupportedAlgorithm(string algorithm) { if (CustomCompressionProvider != null && CustomCompressionProvider.IsSupportedAlgorithm(algorithm)) diff --git a/src/Microsoft.IdentityModel.Tokens/CryptoProviderCache.cs b/src/Microsoft.IdentityModel.Tokens/CryptoProviderCache.cs index 1c9609c70f..5390dad27a 100644 --- a/src/Microsoft.IdentityModel.Tokens/CryptoProviderCache.cs +++ b/src/Microsoft.IdentityModel.Tokens/CryptoProviderCache.cs @@ -37,7 +37,7 @@ public abstract class CryptoProviderCache /// The key used by the cryptographic provider. /// The algorithm used by the cryptographic provider. /// The type of the cryptographic provider obtained by calling object.GetType(). - /// A boolean indicating if the will be used to sign. + /// If true, the provider will be used for creating signatures. /// The if found. /// True if a was found; false otherwise. public abstract bool TryGetSignatureProvider(SecurityKey securityKey, string algorithm, string typeofProvider, bool willCreateSignatures, out SignatureProvider signatureProvider); diff --git a/src/Microsoft.IdentityModel.Tokens/CryptoProviderFactory.cs b/src/Microsoft.IdentityModel.Tokens/CryptoProviderFactory.cs index a94551be69..ca17af29d4 100644 --- a/src/Microsoft.IdentityModel.Tokens/CryptoProviderFactory.cs +++ b/src/Microsoft.IdentityModel.Tokens/CryptoProviderFactory.cs @@ -626,7 +626,7 @@ internal static bool ShouldCacheSignatureProvider(SignatureProvider signaturePro } /// - /// Checks if the specified hash algorithm is supported. + /// Determines whether the specified hash algorithm is supported. /// /// The name of the hash algorithm. /// Considers only known hash algorithms. diff --git a/src/Microsoft.IdentityModel.Tokens/DateTimeUtil.cs b/src/Microsoft.IdentityModel.Tokens/DateTimeUtil.cs index 57b8380bbf..83b8c8c8a2 100644 --- a/src/Microsoft.IdentityModel.Tokens/DateTimeUtil.cs +++ b/src/Microsoft.IdentityModel.Tokens/DateTimeUtil.cs @@ -6,18 +6,18 @@ namespace Microsoft.IdentityModel.Tokens { /// - /// Helper class for adding DateTimes and Timespans. + /// Utility class for performing operations involving and . /// public static class DateTimeUtil { /// - /// Add a DateTime and a TimeSpan. - /// The maximum time is DateTime.MaxTime. It is not an error if time + timespan > MaxTime. - /// Just return MaxTime. + /// Adds a and a . + /// If the resulting value exceeds , returns . + /// If the resulting value is less than , returns . /// /// Initial value. /// to add. - /// as the sum of time and timespan. + /// The sum of and , or if the sum exceeds it, or if the sum is less than it. public static DateTime Add(DateTime time, TimeSpan timespan) { if (timespan == TimeSpan.Zero) @@ -39,10 +39,10 @@ public static DateTime Add(DateTime time, TimeSpan timespan) } /// - /// Gets the Maximum value for a DateTime specifying kind. + /// Gets the maximum value for a with the specified . /// - /// DateTimeKind to use. - /// DateTime of specified kind. + /// The . + /// The maximum value of the specified kind. public static DateTime GetMaxValue(DateTimeKind kind) { if (kind == DateTimeKind.Unspecified) @@ -52,10 +52,10 @@ public static DateTime GetMaxValue(DateTimeKind kind) } /// - /// Gets the Minimum value for a DateTime specifying kind. + /// Gets the minimum value for a with the specified . /// - /// DateTimeKind to use. - /// DateTime of specified kind. + /// The . + /// The minimum value of the specified kind. public static DateTime GetMinValue(DateTimeKind kind) { if (kind == DateTimeKind.Unspecified) @@ -65,10 +65,10 @@ public static DateTime GetMinValue(DateTimeKind kind) } /// - /// Ensures that DataTime is UTC. + /// Converts the specified to UTC if it is not already in UTC. /// - /// to convert. - /// + /// The to convert. + /// The converted in UTC, or null if is null. public static DateTime? ToUniversalTime(DateTime? value) { if (value == null || value.Value.Kind == DateTimeKind.Utc) @@ -78,13 +78,12 @@ public static DateTime GetMinValue(DateTimeKind kind) } /// - /// Ensures that DateTime is UTC. + /// Converts the specified to UTC if it is not already in UTC. /// - /// to convert. - /// + /// The to convert. + /// The converted in UTC. public static DateTime ToUniversalTime(DateTime value) { - if (value.Kind == DateTimeKind.Utc) return value; diff --git a/src/Microsoft.IdentityModel.Tokens/DeflateCompressionProvider.cs b/src/Microsoft.IdentityModel.Tokens/DeflateCompressionProvider.cs index 540458bf66..f92ad14b58 100644 --- a/src/Microsoft.IdentityModel.Tokens/DeflateCompressionProvider.cs +++ b/src/Microsoft.IdentityModel.Tokens/DeflateCompressionProvider.cs @@ -47,7 +47,7 @@ public DeflateCompressionProvider(CompressionLevel compressionLevel) /// /// Gets and sets the maximum deflate size in chars that will be processed. /// - /// 'value' less than 1. + /// Thrown if the value is less than 1. public int MaximumDeflateSize { get => _maximumTokenSizeInBytes; @@ -58,10 +58,10 @@ public int MaximumDeflateSize } /// - /// Decompress the value using DEFLATE algorithm. + /// Decompresses the value using Deflate algorithm. /// - /// the bytes to decompress. - /// the decompressed bytes. + /// The bytes to decompress. + /// The decompressed bytes. public byte[] Decompress(byte[] value) { if (value == null) @@ -101,10 +101,10 @@ public byte[] Decompress(byte[] value) } /// - /// Compress the value using the DEFLATE algorithm. + /// Compresses the value using the Deflate algorithm. /// - /// the bytes to compress. - /// the compressed bytes. + /// The bytes to compress. + /// The compressed bytes. public byte[] Compress(byte[] value) { if (value == null) @@ -125,10 +125,10 @@ public byte[] Compress(byte[] value) } /// - /// Answers if a compression algorithm is supported. + /// Determines whether the specified compression algorithm is supported. /// - /// the name of the compression algorithm. - /// true if the compression algorithm is supported, false otherwise. + /// The name of the compression algorithm. + /// if the compression algorithm is supported; otherwise, . public bool IsSupportedAlgorithm(string algorithm) { return Algorithm.Equals(algorithm); diff --git a/src/Microsoft.IdentityModel.Tokens/ECDsaAdapter.cs b/src/Microsoft.IdentityModel.Tokens/ECDsaAdapter.cs index 6986a9b0ee..32c25b070c 100644 --- a/src/Microsoft.IdentityModel.Tokens/ECDsaAdapter.cs +++ b/src/Microsoft.IdentityModel.Tokens/ECDsaAdapter.cs @@ -12,7 +12,7 @@ namespace Microsoft.IdentityModel.Tokens delegate ECDsa CreateECDsaDelegate(JsonWebKey jsonWebKey, bool usePrivateKey); /// - /// This adapter abstracts the differences between versions of .Net targets. + /// This adapter abstracts the differences between versions of .NET targets. /// internal class ECDsaAdapter { @@ -148,10 +148,10 @@ internal static ECDsa ECDsaNotSupported(JsonWebKey jsonWebKey, bool usePrivateKe } /// - /// Returns the size of key in bytes + /// Determines the key size in bytes based on the specified ECDSA curve identifier. /// - /// Represents ecdsa curve -P256, P384, P521 - /// Size of the key in bytes + /// The identifier of the ECDSA curve (P256, P384, P521). + /// The size of the key in bytes. private static uint GetKeyByteCount(string curveId) { if (string.IsNullOrEmpty(curveId)) @@ -173,11 +173,12 @@ private static uint GetKeyByteCount(string curveId) default: throw LogHelper.LogExceptionMessage(new ArgumentException(LogHelper.FormatInvariant(LogMessages.IDX10645, LogHelper.MarkAsNonPII(curveId)))); } + return keyByteCount; } /// - /// Magic numbers identifying ECDSA blob types + /// Magic numbers identifying ECDSA blob types. /// private enum KeyBlobMagicNumber : uint { @@ -190,11 +191,11 @@ private enum KeyBlobMagicNumber : uint } /// - /// Returns the magic value representing the curve corresponding to the curve id. + /// Returns the magic value representing the curve corresponding to the curve identifier. /// - /// Represents ecdsa curve -P256, P384, P512 - /// Whether the provider will create signatures or not - /// Uint representing the magic number + /// The identifier of the ECDSA curve (P256, P384, P521). + /// If true, the provider will be used for creating signatures. + /// A representing the magic number. private static uint GetMagicValue(string curveId, bool willCreateSignatures) { if (string.IsNullOrEmpty(curveId)) @@ -272,9 +273,9 @@ private static ECDsa CreateECDsaUsingECParams(JsonWebKey jsonWebKey, bool usePri } /// - /// Returns the elliptic curve corresponding to the curve id. + /// Returns the elliptic curve corresponding to the curve identifier. /// - /// Represents ecdsa curve -P256, P384, P512 + /// The identifier of the ECDSA curve (P256, P384, P521). private static ECCurve GetNamedECCurve(string curveId) { if (string.IsNullOrEmpty(curveId)) @@ -311,9 +312,9 @@ internal static string GetCrvParameterValue(ECCurve curve) /// - /// Tests if user application's runtime supports structure. + /// Determines whether user application's runtime supports structure. /// - /// True if structure is supported, false otherwise. + /// if structure is supported; Otherwise . internal static bool SupportsECParameters() { #if NET472 || NET6_0_OR_GREATER diff --git a/src/Microsoft.IdentityModel.Tokens/ECDsaSecurityKey.cs b/src/Microsoft.IdentityModel.Tokens/ECDsaSecurityKey.cs index 61c2496d93..361ba67b75 100644 --- a/src/Microsoft.IdentityModel.Tokens/ECDsaSecurityKey.cs +++ b/src/Microsoft.IdentityModel.Tokens/ECDsaSecurityKey.cs @@ -22,23 +22,23 @@ internal ECDsaSecurityKey(JsonWebKey webKey, bool usePrivateKey) } /// - /// Returns a new instance of . + /// Initializes a new instance of the class. /// - /// + /// The . public ECDsaSecurityKey(ECDsa ecdsa) { ECDsa = ecdsa ?? throw LogHelper.LogArgumentNullException(nameof(ecdsa)); } /// - /// instance used to initialize the key. + /// The instance used to initialize the key. /// public ECDsa ECDsa { get; private set; } /// /// Gets a bool indicating if a private key exists. /// - /// true if it has a private key; otherwise, false. + /// if it has a private key; otherwise, . [System.Obsolete("HasPrivateKey method is deprecated, please use FoundPrivateKey instead.")] public override bool HasPrivateKey { @@ -63,9 +63,13 @@ public override bool HasPrivateKey } /// - /// Gets an enum indicating if a private key exists. + /// Gets a value indicating the existence of the private key. /// - /// 'Exists' if private key exists for sure; 'DoesNotExist' if private key doesn't exist for sure; 'Unknown' if we cannot determine. + /// + /// if the private key exists. + /// if the private key does not exist. + /// if the existence of the private key cannot be determined. + /// public override PrivateKeyStatus PrivateKeyStatus { get @@ -75,7 +79,7 @@ public override PrivateKeyStatus PrivateKeyStatus } /// - /// Gets key size. + /// Gets the key size. /// public override int KeySize { @@ -88,8 +92,8 @@ public override int KeySize /// /// Determines whether the can compute a JWK thumbprint. /// - /// true if JWK thumbprint can be computed; otherwise, false. - /// https://datatracker.ietf.org/doc/html/rfc7638 + /// if JWK thumbprint can be computed; otherwise, . + /// See: . public override bool CanComputeJwkThumbprint() { #if NET472 || NETSTANDARD2_0 || NET6_0_OR_GREATER @@ -100,10 +104,10 @@ public override bool CanComputeJwkThumbprint() } /// - /// Computes a sha256 hash over the . + /// Computes a SHA256 hash over the . /// /// A JWK thumbprint. - /// https://datatracker.ietf.org/doc/html/rfc7638 + /// See: . public override byte[] ComputeJwkThumbprint() { #if NET472 || NETSTANDARD2_0 || NET6_0_OR_GREATER diff --git a/src/Microsoft.IdentityModel.Tokens/EncryptingCredentials.cs b/src/Microsoft.IdentityModel.Tokens/EncryptingCredentials.cs index bf9480adaa..94269926ff 100644 --- a/src/Microsoft.IdentityModel.Tokens/EncryptingCredentials.cs +++ b/src/Microsoft.IdentityModel.Tokens/EncryptingCredentials.cs @@ -19,12 +19,12 @@ public class EncryptingCredentials /// /// Initializes a new instance of the class. /// - /// . + /// The used to encrypt data. /// A key wrap algorithm to use when encrypting a session key. - /// Data encryption algorithm to apply. - /// if 'certificate' is null. - /// if 'alg' is null or empty. - /// if 'enc' is null or empty. + /// The encryption algorithm to apply. + /// Thrown if is null. + /// Thrown if is null or empty. + /// Thrown if is null or empty. protected EncryptingCredentials(X509Certificate2 certificate, string alg, string enc) { if (certificate == null) @@ -38,12 +38,12 @@ protected EncryptingCredentials(X509Certificate2 certificate, string alg, string /// /// Initializes a new instance of the class. /// - /// to use when encrypting a session key. + /// The to use for encryption. /// A key wrap algorithm to use when encrypting a session key. - /// Data encryption algorithm to apply. - /// if 'key' is null. - /// if 'alg' is null or empty. - /// if 'enc' is null or empty. + /// The encryption algorithm to apply. + /// if is null. + /// if is null or empty. + /// if is null or empty. public EncryptingCredentials(SecurityKey key, string alg, string enc) { Key = key; @@ -54,14 +54,15 @@ public EncryptingCredentials(SecurityKey key, string alg, string enc) /// /// Initializes a new instance of the class. /// - /// Used in scenarios when a key represents a 'shared' symmetric key. + /// + /// Used in scenarios when a key represents a 'shared' symmetric key. /// For example, SAML 2.0 Assertion will be encrypted using a provided symmetric key /// which won't be serialized to a SAML token. /// - /// to apply. - /// Data encryption algorithm to apply. - /// If the is not a . - /// if 'enc' is null or empty. + /// The to use for encryption. + /// The encryption algorithm to apply. + /// Thrown if is not a . + /// Thrown if is null or empty. public EncryptingCredentials(SymmetricSecurityKey key, string enc) : this(key, SecurityAlgorithms.None, enc) { @@ -86,7 +87,7 @@ public string Enc } /// - /// Public key used in Key Agreement Algorithms + /// Gets or sets the public key used in Key Agreement Algorithms. /// public SecurityKey KeyExchangePublicKey { get; set; } @@ -97,10 +98,10 @@ public string Enc /// /// Gets or sets a bool that controls if the encrypted token creation will set default 'cty' if not specified. + /// /// /// Applies to only JWT tokens. /// - /// public bool SetDefaultCtyClaim { get; set; } = true; /// diff --git a/src/Microsoft.IdentityModel.Tokens/Encryption/SymmetricKeyWrapProvider.cs b/src/Microsoft.IdentityModel.Tokens/Encryption/SymmetricKeyWrapProvider.cs index 6ee8cb90b5..12e6a1a016 100644 --- a/src/Microsoft.IdentityModel.Tokens/Encryption/SymmetricKeyWrapProvider.cs +++ b/src/Microsoft.IdentityModel.Tokens/Encryption/SymmetricKeyWrapProvider.cs @@ -177,11 +177,11 @@ protected virtual SymmetricAlgorithm GetSymmetricAlgorithm(SecurityKey key, stri } /// - /// Determines if a specified algorithm is supported. + /// Determines whether the specified algorithm is supported. /// /// The to use for cryptographic operations. /// The algorithm to check for support. - /// true if the algorithm is supported; otherwise, false. + /// if the algorithm is supported; otherwise, . protected virtual bool IsSupportedAlgorithm(SecurityKey key, string algorithm) { return SupportedAlgorithms.IsSupportedSymmetricKeyWrap(algorithm, key); diff --git a/src/Microsoft.IdentityModel.Tokens/EpochTime.cs b/src/Microsoft.IdentityModel.Tokens/EpochTime.cs index f891686b5d..b52eff829c 100644 --- a/src/Microsoft.IdentityModel.Tokens/EpochTime.cs +++ b/src/Microsoft.IdentityModel.Tokens/EpochTime.cs @@ -16,12 +16,11 @@ public static class EpochTime public static readonly DateTime UnixEpoch = new DateTime(1970, 1, 1, 0, 0, 0, 0, DateTimeKind.Utc); /// - /// Per JWT spec: /// Gets the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the desired date/time. /// /// The DateTime to convert to seconds. - /// if dateTimeUtc less than UnixEpoch, return 0 - /// the number of seconds since Unix Epoch. + /// If is less than Unix Epoch, returns 0. + /// The number of seconds since Unix Epoch. public static long GetIntDate(DateTime datetime) { DateTime dateTimeUtc = datetime; @@ -39,9 +38,9 @@ public static long GetIntDate(DateTime datetime) } /// - /// Creates a DateTime from epoch time. + /// Creates a from epoch time. /// - /// Number of seconds. + /// The number of seconds since Unix Epoch. /// The DateTime in UTC. public static DateTime DateTime(long secondsSinceUnixEpoch) { diff --git a/src/Microsoft.IdentityModel.Tokens/InMemoryCryptoProviderCache.cs b/src/Microsoft.IdentityModel.Tokens/InMemoryCryptoProviderCache.cs index 00ee2c023f..81b02f6123 100644 --- a/src/Microsoft.IdentityModel.Tokens/InMemoryCryptoProviderCache.cs +++ b/src/Microsoft.IdentityModel.Tokens/InMemoryCryptoProviderCache.cs @@ -145,7 +145,7 @@ public override bool TryAdd(SignatureProvider signatureProvider) /// the key that is used to by the crypto provider. /// the algorithm that is used by the crypto provider. /// the typeof the crypto provider obtained by calling object.GetType(). - /// a bool to indicate if the will be used to sign. + /// If true, the provider will be used for creating signatures. /// the if found. /// if securityKey is null. /// if algorithm is null or empty string. diff --git a/src/Microsoft.IdentityModel.Tokens/SymmetricSignatureProvider.cs b/src/Microsoft.IdentityModel.Tokens/SymmetricSignatureProvider.cs index e066b57f48..5262b0ab8c 100644 --- a/src/Microsoft.IdentityModel.Tokens/SymmetricSignatureProvider.cs +++ b/src/Microsoft.IdentityModel.Tokens/SymmetricSignatureProvider.cs @@ -61,7 +61,7 @@ public SymmetricSignatureProvider(SecurityKey key, string algorithm) /// /// The that will be used for signature operations. /// The signature algorithm to use. - /// indicates if this will be used to create signatures. + /// If true, the provider will be used for creating signatures. /// 'key' is null. /// 'algorithm' is null or empty. /// If and algorithm pair are not supported.