From 0fd8362e13fc5e261b36829de5a3a54b924293a0 Mon Sep 17 00:00:00 2001 From: joegoldman2 <147369450+joegoldman2@users.noreply.github.com> Date: Mon, 8 Jul 2024 21:08:56 +0000 Subject: [PATCH] Refactor XML comments for clarity in Microsoft.IdentityModel.Tokens (#2678) * Refactor XML comments for clarity in Microsoft.IdentityModel.Tokens * Fix typo * Apply suggestions from review * Apply suggestions from review * Fix missing parenthesis * Fix unknown paramref --------- Co-authored-by: joegoldman2 <147369450+joegoldman@users.noreply.github.com> --- .../OpenIdConnectGrantTypes.cs | 10 +- .../AsymmetricAdapter.cs | 5 +- .../AsymmetricSecurityKey.cs | 6 +- .../AsymmetricSignatureProvider.cs | 48 ++- .../Base64UrlEncoder.cs | 58 ++-- .../Base64UrlEncoding.cs | 136 ++++---- .../BaseConfiguration.cs | 18 +- .../BaseConfigurationComparer.cs | 13 +- .../BaseConfigurationManager.cs | 27 +- .../CallContext.cs | 4 +- .../CollectionUtilities.cs | 6 +- .../CompressionAlgorithms.cs | 4 +- .../CompressionProviderFactory.cs | 28 +- .../LKGConfigurationCacheOptions.cs | 4 +- .../CryptoProviderCache.cs | 44 +-- .../CryptoProviderCacheOptions.cs | 7 +- .../CryptoProviderFactory.cs | 306 +++++++++--------- .../AuthenticatedEncryptionProvider.cs | 99 +++--- .../AuthenticatedEncryptionResult.cs | 12 +- .../Encryption/KeyWrapProvider.cs | 20 +- .../Encryption/RsaKeyWrapProvider.cs | 50 +-- .../Encryption/SymmetricKeyWrapProvider.cs | 64 ++-- .../Json/JsonSerializerPrimitives.cs | 44 ++- 23 files changed, 508 insertions(+), 505 deletions(-) diff --git a/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectGrantTypes.cs b/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectGrantTypes.cs index c15c26bb8a..162eb382c1 100644 --- a/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectGrantTypes.cs +++ b/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectGrantTypes.cs @@ -29,27 +29,27 @@ public static class OpenIdConnectGrantTypes public const string ClientCredentials = "client_credentials"; /// - /// Indicates the 'saml2-bearer' grant type. See . + /// Indicates the 'saml2-bearer' grant type. See: . /// public const string Saml2Bearer = "urn:ietf:params:oauth:grant-type:saml2-bearer"; /// - /// Indicates the 'jwt-bearer' grant type. See . + /// Indicates the 'jwt-bearer' grant type. See: . /// public const string JwtBearer = "urn:ietf:params:oauth:grant-type:jwt-bearer"; /// - /// Indicates the 'device_code' grant type. See . + /// Indicates the 'device_code' grant type. See: . /// public const string DeviceCode = "urn:ietf:params:oauth:grant-type:device_code"; /// - /// Indicates the 'token-exchange' grant type. See . + /// Indicates the 'token-exchange' grant type. See: . /// public const string TokenExchange = "urn:ietf:params:oauth:grant-type:token-exchange"; /// - /// Indicates the 'ciba' grant type. See . + /// Indicates the 'ciba' grant type. See: . /// public const string Ciba = "urn:openid:params:grant-type:ciba"; } diff --git a/src/Microsoft.IdentityModel.Tokens/AsymmetricAdapter.cs b/src/Microsoft.IdentityModel.Tokens/AsymmetricAdapter.cs index 349e9b51bb..c1a97f9dcc 100644 --- a/src/Microsoft.IdentityModel.Tokens/AsymmetricAdapter.cs +++ b/src/Microsoft.IdentityModel.Tokens/AsymmetricAdapter.cs @@ -22,7 +22,7 @@ namespace Microsoft.IdentityModel.Tokens delegate bool VerifyUsingOffsetDelegate(byte[] bytes, int offset, int count, byte[] signature); /// - /// This adapter abstracts the 'RSA' differences between versions of .Net targets. + /// This adapter abstracts the 'RSA' differences between versions of .NET targets. /// internal class AsymmetricAdapter : IDisposable { @@ -102,7 +102,7 @@ internal static byte[] DecryptFunctionNotFound(byte[] _) } /// - /// Calls and + /// Calls and . /// public void Dispose() { @@ -460,7 +460,6 @@ private bool VerifyWithRsaCryptoServiceProviderProxyUsingOffset(byte[] bytes, in { return RsaCryptoServiceProviderProxy.VerifyDataWithLength(bytes, offset, length, HashAlgorithm, HashAlgorithmName, signature); } - #endif #endregion diff --git a/src/Microsoft.IdentityModel.Tokens/AsymmetricSecurityKey.cs b/src/Microsoft.IdentityModel.Tokens/AsymmetricSecurityKey.cs index 7a682a20f3..708df36b2c 100644 --- a/src/Microsoft.IdentityModel.Tokens/AsymmetricSecurityKey.cs +++ b/src/Microsoft.IdentityModel.Tokens/AsymmetricSecurityKey.cs @@ -4,12 +4,12 @@ namespace Microsoft.IdentityModel.Tokens { /// - /// Base class for a Security Key that contains Asymmetric key material. + /// Base class for a that contains Asymmetric key material. /// public abstract class AsymmetricSecurityKey : SecurityKey { /// - /// Default constructor + /// Initializes a new instance of the class. /// public AsymmetricSecurityKey() { @@ -30,7 +30,7 @@ internal AsymmetricSecurityKey(SecurityKey key) /// /// Gets the status 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 private key exists for sure; if private key doesn't exist for sure; if we cannot determine. public abstract PrivateKeyStatus PrivateKeyStatus { get; } } diff --git a/src/Microsoft.IdentityModel.Tokens/AsymmetricSignatureProvider.cs b/src/Microsoft.IdentityModel.Tokens/AsymmetricSignatureProvider.cs index 682314e625..6183e64781 100644 --- a/src/Microsoft.IdentityModel.Tokens/AsymmetricSignatureProvider.cs +++ b/src/Microsoft.IdentityModel.Tokens/AsymmetricSignatureProvider.cs @@ -92,26 +92,18 @@ public AsymmetricSignatureProvider(SecurityKey key, string algorithm) } /// - /// Initializes a new instance of the class used to create and verify signatures. + /// Initializes a new instance of the class used for creating and verifying signatures. /// /// The that will be used for signature operations. /// The signature algorithm to apply. - /// If this is required to create signatures then set this to true. - /// - /// Creating signatures requires that the has access to a private key. - /// Verifying signatures (the default), does not require access to the private key. - /// - /// is null. - /// is null or empty. - /// is true and there is no private key. - /// If and algorithm pair are not supported. - /// - /// willCreateSignatures is true and .KeySize is less than the size corresponding to the given algorithm in . - /// - /// - /// .KeySize is less than the size corresponding to the algorithm in . Note: this is always checked. - /// - /// If the runtime is unable to create a suitable cryptographic provider. + /// If true, the provider will be used for creating signatures; otherwise, it will be used for verifying signatures. + /// Thrown if is null. + /// Thrown if is null or empty. + /// Thrown if is true and there is no private key available. + /// Thrown if the and algorithm pair are not supported. + /// Thrown if is true and is less than the required size for signing. + /// Thrown if is less than the required size for verifying signatures. + /// Thrown if the runtime is unable to create a suitable cryptographic provider. public AsymmetricSignatureProvider(SecurityKey key, string algorithm, bool willCreateSignatures) : base(key, algorithm) { @@ -167,8 +159,8 @@ private static PrivateKeyStatus FoundPrivateKey(SecurityKey key) /// /// The SignatureAlgorithm in use. /// The to use. - /// if is null or whitespace. - /// if is not supported. + /// Thrown if is null or whitespace. + /// Thrown if is not supported. protected virtual HashAlgorithmName GetHashAlgorithmName(string algorithm) { if (string.IsNullOrWhiteSpace(algorithm)) @@ -233,9 +225,8 @@ public override bool Sign(ReadOnlySpan input, Span signature, out in /// /// The bytes to be signed. /// A signature over the input. - /// if is null. - /// if .Length == 0. - /// If has been called. + /// Thrown if is null or has length of 0. + /// Thrown If has been called. /// Sign is thread safe. public override byte[] Sign(byte[] input) { @@ -304,10 +295,9 @@ public override byte[] Sign(byte[] input, int offset, int count) /// The asymmetric key to validate. /// Algorithm for which this key will be used. /// Whether they key will be used for creating signatures. - /// if is null. - /// if is null or empty. - /// if .KeySize is less than the minimum - /// acceptable size. + /// Thrown if is null. + /// Thrown if is null or empty. + /// Thrown if is less than the minimum acceptable size. /// /// for minimum signing sizes. /// for minimum verifying sizes. @@ -359,9 +349,9 @@ public virtual void ValidateAsymmetricSecurityKeySize(SecurityKey key, string al /// The bytes to generate the signature over. /// The value to verify against. /// true if signature matches, false otherwise. - /// is null or has length == 0. - /// is null or has length == 0. - /// If has been called. + /// Thrown if is null or has length of 0. + /// Thrown if is null or has length of 0. + /// Thrown if has been called. /// Verify is thread safe. public override bool Verify(byte[] input, byte[] signature) { diff --git a/src/Microsoft.IdentityModel.Tokens/Base64UrlEncoder.cs b/src/Microsoft.IdentityModel.Tokens/Base64UrlEncoder.cs index cb1ed39940..3058a55f5d 100644 --- a/src/Microsoft.IdentityModel.Tokens/Base64UrlEncoder.cs +++ b/src/Microsoft.IdentityModel.Tokens/Base64UrlEncoder.cs @@ -12,7 +12,7 @@ namespace Microsoft.IdentityModel.Tokens { /// - /// Encodes and Decodes strings as Base64Url encoding. + /// Encodes and Decodes strings as base64url encoding. /// public static class Base64UrlEncoder { @@ -23,13 +23,13 @@ public static class Base64UrlEncoder private const char base64UrlCharacter63 = '_'; /// - /// The following functions perform base64url encoding which differs from regular base64 encoding as follows - /// * padding is skipped so the pad character '=' doesn't have to be percent encoded - /// * the 62nd and 63rd regular base64 encoding characters ('+' and '/') are replace with ('-' and '_') - /// The changes make the encoding alphabet file and URL safe. + /// Performs base64url encoding, which differs from regular base64 encoding as follows: + /// * Padding is skipped so the pad character '=' doesn't have to be percent encoded. + /// * The 62nd and 63rd regular base64 encoding characters ('+' and '/') are replaced with ('-' and '_'). + /// This makes the encoding alphabet URL safe. /// - /// string to encode. - /// Base64Url encoding of the UTF8 bytes. + /// The string to encode. + /// The base64url encoding of the UTF8 bytes. public static string Encode(string arg) { _ = arg ?? throw LogHelper.LogArgumentNullException(nameof(arg)); @@ -38,12 +38,12 @@ public static string Encode(string arg) } /// - /// Converts a subset of an array of 8-bit unsigned integers to its equivalent string representation which is encoded with base-64-url digits. + /// Converts a subset of an array of 8-bit unsigned integers to its equivalent string representation encoded with base64url digits. /// /// An array of 8-bit unsigned integers. - /// The string representation in base 64 url encoding of length elements of inArray, starting at position offset. - /// 'inArray' is null. - /// offset or length is negative OR offset plus length is greater than the length of inArray. + /// The base64url encoded string representation of the elements in inArray. + /// Thrown if inArray is null. + /// Thrown if offset or length is negative, or if offset plus length is greater than the length of inArray. public static string Encode(byte[] inArray) { _ = inArray ?? throw LogHelper.LogArgumentNullException(nameof(inArray)); @@ -52,15 +52,15 @@ public static string Encode(byte[] inArray) } /// - /// Converts a subset of an array of 8-bit unsigned integers to its equivalent string representation which is encoded with base-64-url digits. Parameters specify - /// the subset as an offset in the input array, and the number of elements in the array to convert. + /// Converts a subset of an array of 8-bit unsigned integers to its equivalent string representation encoded with base64url digits. + /// Parameters specify the subset as an offset in the input array and the number of elements in the array to convert. /// /// An array of 8-bit unsigned integers. - /// An offset in inArray. - /// The number of elements of inArray to convert. - /// The string representation in base 64 url encoding of length elements of inArray, starting at position offset. - /// 'inArray' is null. - /// offset or length is negative OR offset plus length is greater than the length of inArray. + /// An offset in inArray. + /// The number of elements of inArray to convert. + /// The base64url encoded string representation of length elements of inArray, starting at position offset. + /// Thrown if inArray is null. + /// Thrown if offset or length is negative, or if offset plus length is greater than the length of inArray. public static string Encode(byte[] inArray, int offset, int length) { _ = inArray ?? throw LogHelper.LogArgumentNullException(nameof(inArray)); @@ -105,12 +105,11 @@ public static string Encode(byte[] inArray, int offset, int length) } /// - /// Populates a Converts a encoded with base-64-url digits. Parameters specify - /// the subset as an offset in the input array, and the number of elements in the array to convert. + /// Populates a with the base64url encoded representation of a of bytes. /// - /// A span of bytes. - /// output for encoding. - /// The number of chars written to the output. + /// A read-only span of bytes to encode. + /// The span of characters to write the encoded output. + /// The number of characters written to the output span. public static int Encode(ReadOnlySpan inArray, Span output) { int lengthmod3 = inArray.Length % 3; @@ -167,9 +166,10 @@ public static int Encode(ReadOnlySpan inArray, Span output) } /// - /// Converts the specified string, base-64-url encoded to utf8 bytes. - /// base64Url encoded string. - /// UTF8 bytes. + /// Converts the specified base64url encoded string to UTF-8 bytes. + /// + /// The base64url encoded string. + /// The UTF-8 bytes. public static byte[] DecodeBytes(string str) { _ = str ?? throw LogHelper.LogExceptionMessage(new ArgumentNullException(nameof(str))); @@ -357,10 +357,10 @@ private static void Decode(ReadOnlySpan strSpan, Span output, bool n #endif /// - /// Decodes the string from Base64UrlEncoded to UTF8. + /// Decodes the specified base64url encoded string to UTF-8. /// - /// string to decode. - /// UTF8 string. + /// The base64url encoded string to decode. + /// The UTF-8 decoded string. public static string Decode(string arg) { return Encoding.UTF8.GetString(DecodeBytes(arg)); diff --git a/src/Microsoft.IdentityModel.Tokens/Base64UrlEncoding.cs b/src/Microsoft.IdentityModel.Tokens/Base64UrlEncoding.cs index 202d9f4f1a..558aaf54bf 100644 --- a/src/Microsoft.IdentityModel.Tokens/Base64UrlEncoding.cs +++ b/src/Microsoft.IdentityModel.Tokens/Base64UrlEncoding.cs @@ -26,19 +26,19 @@ internal static class Base64UrlEncoding private const uint IntUnderscore = '_'; private static readonly char[] Base64Table = - { - 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', - 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', 'a', 'b', 'c', 'd', - 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', - 't', 'u', 'v', 'w', 'x', 'y', 'z', '0', '1', '2', '3', '4', '5', '6', '7', - '8', '9', '-', '_', - }; + { + 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', + 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', 'a', 'b', 'c', 'd', + 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', + 't', 'u', 'v', 'w', 'x', 'y', 'z', '0', '1', '2', '3', '4', '5', '6', '7', + '8', '9', '-', '_', + }; /// - /// Decodes a Base64UrlEncoded string into a byte array. + /// Decodes a base64url encoded string into a byte array. /// - /// The string to decode. - /// Decoded bytes. + /// The base64url encoded string to decode. + /// The decoded bytes. public static byte[] Decode(string inputString) { _ = inputString ?? throw LogHelper.LogArgumentNullException(nameof(inputString)); @@ -47,12 +47,12 @@ public static byte[] Decode(string inputString) } /// - /// Decodes a Base64UrlEncoded string into a byte array. + /// Decodes a base64url encoded substring of a string into a byte array. /// - /// String to decode. - /// Index of char in to start decode operation. - /// Number of chars in to decode. - /// Decoded bytes. + /// The base64url encoded string to decode. + /// The index of the character in to start decoding. + /// The number of characters in to decode. + /// The decoded bytes. public static byte[] Decode(string input, int offset, int length) { _ = input ?? throw LogHelper.LogArgumentNullException(nameof(input)); @@ -65,19 +65,19 @@ public static byte[] Decode(string input, int offset, int length) } /// - /// Decodes a Base64UrlEncoded string and then performs an action. + /// Decodes a base64url encoded substring of a string and then performs an action on the decoded bytes. /// - /// String to decode. - /// Index of char in to start decode operation. - /// Number of chars in to decode from . - /// Input parameter to action. - /// Action to perform on decoded bytes. - /// Output type of decoding action. - /// Type of Input parameter to action. - /// Instance of {T}. + /// The output type of the decoding action. + /// The type of the input parameter to the action. + /// The base64url encoded string to decode. + /// The index of the character in to start decoding. + /// The number of characters in to decode from . + /// The input parameter to the action. + /// The action to perform on the decoded bytes. + /// An instance of {T}. /// - /// The buffer for the decode operation uses shared memory pool to avoid allocations. - /// The length of the rented array of bytes may be larger than the decoded bytes, therefore the action needs to know the actual length to use. + /// The buffer for the decode operation uses a shared memory pool to avoid allocations. + /// The length of the rented array of bytes may be larger than the decoded bytes; therefore, the action needs to know the actual length to use. /// The result of is passed to the action. /// public static T Decode(string input, int offset, int length, TX argx, Func action) @@ -99,17 +99,17 @@ public static T Decode(string input, int offset, int length, TX argx, Fun } /// - /// Decodes a Base64UrlEncoded string and then performs an action. + /// Decodes a base64url encoded substring of a string and then performs an action on the decoded bytes. /// - /// The string to decode. - /// Index of char in to start decode operation from. - /// Count of char in to decode. - /// Action to perform on decoded bytes. - /// Return type of operation. - /// Instance of {T}. + /// The return type of the operation. + /// The base64url encoded string to decode. + /// The index of the character in to start decoding from. + /// The number of characters in to decode from . + /// The action to perform on the decoded bytes. + /// An instance of {T}. /// - /// The buffer for the decode operation uses shared memory pool to avoid allocations. - /// The length of the rented array of bytes may be larger than the decoded bytes, therefore the action needs to know the actual length to use. + /// The buffer for the decode operation uses a shared memory pool to avoid allocations. + /// The length of the rented array of bytes may be larger than the decoded bytes; therefore, the action needs to know the actual length to use. /// The result of is passed to the action. /// public static T Decode(string input, int offset, int length, Func action) @@ -132,23 +132,23 @@ public static T Decode(string input, int offset, int length, Func - /// Decodes a Base64UrlEncoded string and then performs an action. + /// Decodes a base64url encoded substring of a string and then performs an action on the decoded bytes. /// - /// The string to decode. - /// Index of char in to start decode operation from. - /// Count of char in to decode. - /// Input parameter 1 to action. - /// Input parameter 2 to action. - /// Input parameter 3 to action. - /// Action to perform on decoded bytes. - /// Output type of decoding action. - /// Type of Input parameter 1 to action. - /// Type of Input parameter 2 to action. - /// Type of Input parameter 3 to action. - /// Instance of {T}. + /// The return type of the operation. + /// The type of input parameter 1 to the action. + /// The type of input parameter 2 to the action. + /// The type of input parameter 3 to the action. + /// The base64url encoded string to decode. + /// The index of the character in to start decoding from. + /// The number of characters in to decode from . + /// Input parameter 1 to the action. + /// Input parameter 2 to the action. + /// Input parameter 3 to the action. + /// The action to perform on the decoded bytes. + /// An instance of {T}. /// - /// The buffer for the decode operation uses shared memory pool to avoid allocations. - /// The length of the rented array of bytes may be larger than the decoded bytes, therefore the action needs to know the actual length to use. + /// The buffer for the decode operation uses a shared memory pool to avoid allocations. + /// The length of the rented array of bytes may be larger than the decoded bytes; therefore, the action needs to know the actual length to use. /// The result of is passed to the action. /// public static T Decode( @@ -177,14 +177,14 @@ public static T Decode( } /// - /// Decodes a Base64UrlEncoded string into a byte array. + /// Decodes a Base64Url encoded substring of a string into a byte array. /// - /// String represented as a span to decode. - /// Index of char in to start decode operation. - /// Number of chars beginning from to decode. - /// byte array to place results. + /// The string represented as a span to decode. + /// The index of the character in to start decoding from. + /// The number of characters beginning from to decode. + /// The byte array to place the decoded results into. /// - /// Changes from Base64UrlEncoder implementation + /// Changes from Base64UrlEncoder implementation: /// 1. Padding is optional. /// 2. '+' and '-' are treated the same. /// 3. '/' and '_' are treated the same. @@ -266,10 +266,10 @@ internal static void Decode(ReadOnlySpan input, int offset, int length, by } /// - /// Encode byte array to Base64UrlEncoded string. + /// Encodes a byte array into a base64url encoded string. /// - /// Bytes to encode. - /// Base64Url encoded string. + /// The bytes to encode. + /// base64url encoded string. public static string Encode(byte[] bytes) { _ = bytes ?? throw LogHelper.LogArgumentNullException(nameof(bytes)); @@ -277,11 +277,11 @@ public static string Encode(byte[] bytes) } /// - /// Encode byte array to Base64UrlEncoded string. + /// Encodes a subset of a byte array into a Base64Url encoded string. /// - /// Bytes to encode. - /// Index into to start encode operation. - /// Number of bytes in to encode, starting from offset. + /// The byte array to encode. + /// The index into to start the encode operation. + /// The number of bytes in to encode, starting from . /// Base64Url encoded string. public static string Encode(byte[] input, int offset, int length) { @@ -332,12 +332,12 @@ public static string Encode(byte[] input, int offset, int length) } /// - /// Validates the input span for decode operation. + /// Validates the input span for a decode operation. /// - /// String represented by a span to validate. - /// Index of char in to start decode operation. - /// Number of chars in to decode, starting from offset. - /// Size of the decoded bytes arrays. + /// The string represented by a span to validate. + /// The index of the character in to start the decode operation. + /// The number of characters in to decode, starting from . + /// The size of the decoded bytes array. internal static int ValidateAndGetOutputSize(ReadOnlySpan strSpan, int offset, int length) { if (strSpan.IsEmpty) diff --git a/src/Microsoft.IdentityModel.Tokens/BaseConfiguration.cs b/src/Microsoft.IdentityModel.Tokens/BaseConfiguration.cs index 6f25f80c54..623924d8d1 100644 --- a/src/Microsoft.IdentityModel.Tokens/BaseConfiguration.cs +++ b/src/Microsoft.IdentityModel.Tokens/BaseConfiguration.cs @@ -8,7 +8,7 @@ namespace Microsoft.IdentityModel.Tokens { /// - /// Represents a generic metadata configuration which is applicable for both XML and JSON based configurations. + /// Represents a generic metadata configuration which is applicable for both XML and JSON based configurations. /// public abstract class BaseConfiguration { @@ -20,21 +20,18 @@ public abstract class BaseConfiguration /// /// Gets the that the IdentityProvider indicates are to be used in order to sign tokens. /// - public virtual ICollection SigningKeys - { - get; - } = new Collection(); + public virtual ICollection SigningKeys { get; } = new Collection(); /// /// Gets or sets the token endpoint specified via the metadata endpoint. - /// This is the fed:PassiveRequestorEndpoint in WS-Federation, https://docs.oasis-open.org/wsfed/federation/v1.2/os/ws-federation-1.2-spec-os.html#:~:text=fed%3ASecurityTokenServiceType/fed%3APassiveRequestorEndpoint - /// Or the token_endpoint in the OIDC metadata. + /// This is the fed:PassiveRequestorEndpoint in WS-Federation () + /// or the token_endpoint in the OIDC metadata. /// public virtual string TokenEndpoint { get; set; } /// /// Gets or sets the token endpoint specified via the metadata endpoint. - /// This is the fed:SecurityTokenServiceType in WS-Federation, http://docs.oasis-open.org/wsfed/federation/v1.2/os/ws-federation-1.2-spec-os.html#:~:text=fed%3ASecurityTokenSerivceEndpoint + /// This is the fed:SecurityTokenServiceType in WS-Federation () /// public virtual string ActiveTokenEndpoint { get; set; } @@ -42,9 +39,6 @@ public virtual ICollection SigningKeys /// Gets the that the IdentityProvider indicates are to be used in order to decrypt tokens. /// [JsonIgnore] - public virtual ICollection TokenDecryptionKeys - { - get; - } = new Collection(); + public virtual ICollection TokenDecryptionKeys { get; } = new Collection(); } } diff --git a/src/Microsoft.IdentityModel.Tokens/BaseConfigurationComparer.cs b/src/Microsoft.IdentityModel.Tokens/BaseConfigurationComparer.cs index 6c08fcd60c..28413ea56c 100644 --- a/src/Microsoft.IdentityModel.Tokens/BaseConfigurationComparer.cs +++ b/src/Microsoft.IdentityModel.Tokens/BaseConfigurationComparer.cs @@ -6,10 +6,16 @@ namespace Microsoft.IdentityModel.Tokens { /// - /// Comparison class for a . + /// Compares instances of for equality. /// internal class BaseConfigurationComparer : IEqualityComparer { + /// + /// Determines whether the specified objects are equal. + /// + /// The first to compare. + /// The second to compare. + /// true if the specified objects are equal; otherwise, false. public bool Equals(BaseConfiguration config1, BaseConfiguration config2) { if (config1 == null && config2 == null) @@ -43,6 +49,11 @@ private static bool ContainsKeyWithInternalId(BaseConfiguration config, string i return false; } + /// + /// Returns a hash code for the specified object. + /// + /// The for which a hash code is to be returned. + /// A hash code for the specified object. public int GetHashCode(BaseConfiguration config) { int defaultHash = string.Empty.GetHashCode(); diff --git a/src/Microsoft.IdentityModel.Tokens/BaseConfigurationManager.cs b/src/Microsoft.IdentityModel.Tokens/BaseConfigurationManager.cs index 042f69ba5c..63504b58c4 100644 --- a/src/Microsoft.IdentityModel.Tokens/BaseConfigurationManager.cs +++ b/src/Microsoft.IdentityModel.Tokens/BaseConfigurationManager.cs @@ -40,29 +40,30 @@ public TimeSpan AutomaticRefreshInterval } /// - /// 12 hours is the default time interval that afterwards will obtain new configuration. + /// Default time interval (12 hours) after which a new configuration is obtained automatically. /// public static readonly TimeSpan DefaultAutomaticRefreshInterval = new TimeSpan(0, 12, 0, 0); /// - /// 1 hour is the default time interval that a last known good configuration will last for. + /// Default time interval (1 hour) for which the last known good configuration remains valid. /// public static readonly TimeSpan DefaultLastKnownGoodConfigurationLifetime = new TimeSpan(0, 1, 0, 0); /// - /// 5 minutes is the default time interval that must pass for to obtain a new configuration. + /// Default time interval (5 minutes) that must pass for to obtain a new configuration. /// public static readonly TimeSpan DefaultRefreshInterval = new TimeSpan(0, 0, 5, 0); /// - /// The default constructor. + /// Initializes a new instance of the class. /// - public BaseConfigurationManager() : this(new LKGConfigurationCacheOptions()) + public BaseConfigurationManager() + : this(new LKGConfigurationCacheOptions()) { } /// - /// Constructor. + /// Initializes a new instance of the class. /// /// The event queue task creation option. public BaseConfigurationManager(LKGConfigurationCacheOptions options) @@ -81,10 +82,10 @@ public BaseConfigurationManager(LKGConfigurationCacheOptions options) /// Obtains an updated version of if the appropriate refresh interval has passed. /// This method may return a cached version of the configuration. /// - /// CancellationToken + /// A cancellation token that can be used to cancel the asynchronous operation. /// Configuration of type Configuration. - /// This method on the base class throws a as it is meant to be - /// overridden by the class that extends it. + /// This method on the base class throws a + /// as it is meant to be overridden by the class that extends it. public virtual Task GetBaseConfigurationAsync(CancellationToken cancel) { throw new NotImplementedException(); @@ -139,12 +140,12 @@ public TimeSpan LastKnownGoodLifetime public string MetadataAddress { get; set; } /// - /// 5 minutes is the minimum value for automatic refresh. can not be set less than this value. + /// Minimum time interval (5 minutes) for automatic refresh. cannot be set to less than this value. /// public static readonly TimeSpan MinimumAutomaticRefreshInterval = new TimeSpan(0, 0, 5, 0); /// - /// 1 second is the minimum time interval that must pass for to obtain new configuration. + /// Minimum time interval (1 second) that must pass before calling to obtain new configuration. /// public static readonly TimeSpan MinimumRefreshInterval = new TimeSpan(0, 0, 0, 1); @@ -164,12 +165,12 @@ public TimeSpan RefreshInterval } /// - /// Indicates whether the last known good feature should be used, true by default. + /// Gets or sets a value indicating whether to use the last known good configuration. Default is true. /// public bool UseLastKnownGoodConfiguration { get; set; } = true; /// - /// Indicates whether the last known good configuration is still fresh, depends on when the LKG was first used and it's lifetime. + /// Gets a value indicating whether the last known good configuration is still valid, depends on when the LKG was first used and it's lifetime. /// // The _lastKnownGoodConfiguration private variable is accessed rather than the property (LastKnownGoodConfiguration) as we do not want this access // to trigger a change in _lastKnownGoodConfigFirstUse. diff --git a/src/Microsoft.IdentityModel.Tokens/CallContext.cs b/src/Microsoft.IdentityModel.Tokens/CallContext.cs index 7037743e71..5b4a8b6d7a 100644 --- a/src/Microsoft.IdentityModel.Tokens/CallContext.cs +++ b/src/Microsoft.IdentityModel.Tokens/CallContext.cs @@ -12,14 +12,14 @@ namespace Microsoft.IdentityModel.Tokens public class CallContext : LoggerContext { /// - /// Instantiates a new with a default activityId. + /// Instantiates a new with a default activity identifier. /// public CallContext() : base() { } /// - /// Instantiates a new with an activityId. + /// Instantiates a new with an activity identifier. /// public CallContext(Guid activityId) : base(activityId) { diff --git a/src/Microsoft.IdentityModel.Tokens/CollectionUtilities.cs b/src/Microsoft.IdentityModel.Tokens/CollectionUtilities.cs index c77619bf9e..9935b396d3 100644 --- a/src/Microsoft.IdentityModel.Tokens/CollectionUtilities.cs +++ b/src/Microsoft.IdentityModel.Tokens/CollectionUtilities.cs @@ -12,11 +12,11 @@ namespace Microsoft.IdentityModel.Tokens public static class CollectionUtilities { /// - /// Checks whether is null or empty. + /// Checks whether the specified is null or empty. /// - /// The type of the . + /// The type of the elements in the . /// The to be checked. - /// True if is null or empty, false otherwise. + /// True if the is null or contains no elements; otherwise, false. public static bool IsNullOrEmpty(this IEnumerable enumerable) { return enumerable == null || !enumerable.Any(); diff --git a/src/Microsoft.IdentityModel.Tokens/CompressionAlgorithms.cs b/src/Microsoft.IdentityModel.Tokens/CompressionAlgorithms.cs index 55fbe915dd..c12ff23976 100644 --- a/src/Microsoft.IdentityModel.Tokens/CompressionAlgorithms.cs +++ b/src/Microsoft.IdentityModel.Tokens/CompressionAlgorithms.cs @@ -10,7 +10,9 @@ namespace Microsoft.IdentityModel.Tokens /// public class CompressionAlgorithms { - // See: https://datatracker.ietf.org/doc/html/rfc1951 + /// + /// See: . + /// public const string Deflate = "DEF"; } } diff --git a/src/Microsoft.IdentityModel.Tokens/CompressionProviderFactory.cs b/src/Microsoft.IdentityModel.Tokens/CompressionProviderFactory.cs index c4379aa987..cec29c53de 100644 --- a/src/Microsoft.IdentityModel.Tokens/CompressionProviderFactory.cs +++ b/src/Microsoft.IdentityModel.Tokens/CompressionProviderFactory.cs @@ -22,16 +22,16 @@ static CompressionProviderFactory() } /// - /// Default constructor for . + /// Initializes a new instance of the class. /// public CompressionProviderFactory() { } /// - /// Constructor that creates a deep copy of given object. + /// Initializes a new instance of the class. /// - /// to copy from. + /// The to copy from. public CompressionProviderFactory(CompressionProviderFactory other) { if (other == null) @@ -55,10 +55,10 @@ public static CompressionProviderFactory Default public ICompressionProvider CustomCompressionProvider { get; set; } /// - /// Answers if an algorithm is supported. + /// Checks if the specified cryptographic algorithm is supported. /// - /// the name of the crypto algorithm. - /// true if the algorithm is supported, false otherwise. + /// The name of the cryptographic algorithm. + /// True if the algorithm is supported; otherwise, false. public virtual bool IsSupportedAlgorithm(string algorithm) { if (CustomCompressionProvider != null && CustomCompressionProvider.IsSupportedAlgorithm(algorithm)) @@ -73,21 +73,21 @@ private static bool IsSupportedCompressionAlgorithm(string algorithm) } /// - /// Returns a for a specific algorithm. + /// Creates a for a specified compression algorithm. /// - /// the decompression algorithm. - /// a . + /// The compression algorithm. + /// An instance of for the specified algorithm. public ICompressionProvider CreateCompressionProvider(string algorithm) { return CreateCompressionProvider(algorithm, TokenValidationParameters.DefaultMaximumTokenSizeInBytes); } /// - /// Returns a for a specific algorithm. + /// Creates a for a specific compression algorithm with a maximum deflate size limit. /// - /// the decompression algorithm. - /// the maximum deflate size in chars that will be processed. - /// a . + /// The compression algorithm. + /// The maximum size limit (in characters) for deflate compression processing. + /// A instance. public ICompressionProvider CreateCompressionProvider(string algorithm, int maximumDeflateSize) { if (string.IsNullOrEmpty(algorithm)) @@ -101,7 +101,5 @@ public ICompressionProvider CreateCompressionProvider(string algorithm, int maxi throw LogHelper.LogExceptionMessage(new NotSupportedException(LogHelper.FormatInvariant(LogMessages.IDX10652, LogHelper.MarkAsNonPII(algorithm)))); } - } } - diff --git a/src/Microsoft.IdentityModel.Tokens/Configuration/LKGConfigurationCacheOptions.cs b/src/Microsoft.IdentityModel.Tokens/Configuration/LKGConfigurationCacheOptions.cs index d6dc342b5d..53d6df4b50 100644 --- a/src/Microsoft.IdentityModel.Tokens/Configuration/LKGConfigurationCacheOptions.cs +++ b/src/Microsoft.IdentityModel.Tokens/Configuration/LKGConfigurationCacheOptions.cs @@ -22,7 +22,7 @@ public class LKGConfigurationCacheOptions public static readonly int DefaultLKGConfigurationSizeLimit = 10; /// - /// Gets or sets the BaseConfgiurationComparer that to compare . + /// Gets or sets the that is used to determine equality of values for . /// public IEqualityComparer BaseConfigurationComparer { @@ -31,7 +31,7 @@ public IEqualityComparer BaseConfigurationComparer } /// - /// The size limit of the cache (in number of items) for last known good configuration. + /// Gets or sets the size limit of the cache (in number of items) for last known good configuration. /// public int LastKnownGoodConfigurationSizeLimit { diff --git a/src/Microsoft.IdentityModel.Tokens/CryptoProviderCache.cs b/src/Microsoft.IdentityModel.Tokens/CryptoProviderCache.cs index a60679341b..1c9609c70f 100644 --- a/src/Microsoft.IdentityModel.Tokens/CryptoProviderCache.cs +++ b/src/Microsoft.IdentityModel.Tokens/CryptoProviderCache.cs @@ -4,49 +4,49 @@ namespace Microsoft.IdentityModel.Tokens { /// - /// Definition of cache for crypto providers + /// Abstract definition of a cache for cryptographic providers. /// public abstract class CryptoProviderCache { /// - /// Returns the cache key to use when looking up an entry into the cache for a + /// Returns the cache key used to look up an entry for a . /// - /// the to create the key for. - /// the cache key to use for finding a . + /// The to create the key for. + /// The cache key used for finding a . protected abstract string GetCacheKey(SignatureProvider signatureProvider); /// - /// Returns the 'key' that will be used to find a crypto provider in this cache. + /// Returns the cache key used to find a cryptographic provider in this cache. /// - /// 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(). - /// the cache key to use for finding a crypto provider. + /// 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(). + /// The cache key used for finding a cryptographic provider. protected abstract string GetCacheKey(SecurityKey securityKey, string algorithm, string typeofProvider); /// - /// Trys to adds a to this cache. + /// Tries to add a to this cache. /// - /// to cache. - /// true if the was added, false if the cache already contained the + /// The to cache. + /// True if the was added; false if the cache already contained the . public abstract bool TryAdd(SignatureProvider signatureProvider); /// - /// Trys to find a in this cache. + /// Tries to find a in this cache. /// - /// 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. - /// the if found. - /// true if a was found, false otherwise. + /// 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. + /// 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); /// - /// Trys to remove a from this cache. + /// Tries to remove a from this cache. /// - /// to remove. - /// true if the was removed, false if the was not found. + /// The to remove. + /// True if the was removed; false if the was not found. public abstract bool TryRemove(SignatureProvider signatureProvider); } } diff --git a/src/Microsoft.IdentityModel.Tokens/CryptoProviderCacheOptions.cs b/src/Microsoft.IdentityModel.Tokens/CryptoProviderCacheOptions.cs index ce9e0bb918..cb5a08aa44 100644 --- a/src/Microsoft.IdentityModel.Tokens/CryptoProviderCacheOptions.cs +++ b/src/Microsoft.IdentityModel.Tokens/CryptoProviderCacheOptions.cs @@ -16,14 +16,13 @@ public class CryptoProviderCacheOptions private int _sizeLimit = DefaultSizeLimit; /// - /// Default value for . + /// Default value for the cache size limit (). Default is 1000. /// public static readonly int DefaultSizeLimit = 1000; /// - /// Gets or sets the size of the cache (in number of items). - /// 20% of the cache will be evicted whenever the cache gets to 95% of this size. - /// Items will be evicted from least recently used to most recently used. + /// Gets or sets the size limit of the cache (in number of items). + /// When the cache reaches 95% of this size, 20% of the least recently used items will be evicted. /// public int SizeLimit { diff --git a/src/Microsoft.IdentityModel.Tokens/CryptoProviderFactory.cs b/src/Microsoft.IdentityModel.Tokens/CryptoProviderFactory.cs index 3ce56064ad..a94551be69 100644 --- a/src/Microsoft.IdentityModel.Tokens/CryptoProviderFactory.cs +++ b/src/Microsoft.IdentityModel.Tokens/CryptoProviderFactory.cs @@ -56,7 +56,7 @@ static CryptoProviderFactory() } /// - /// Default constructor for . + /// Initializes a new instance of the class. /// public CryptoProviderFactory() { @@ -64,20 +64,18 @@ public CryptoProviderFactory() } /// - /// Initializes an instance of a . + /// Initializes a new instance of the class. /// - /// - /// The cache to use for caching CryptoProviders - /// + /// The cache to use for caching CryptoProviders. public CryptoProviderFactory(CryptoProviderCache cache) { CryptoProviderCache = cache ?? throw LogHelper.LogArgumentNullException(nameof(cache)); } /// - /// Constructor that creates a deep copy of given object. + /// Initializes a new instance of the class. /// - /// to copy from. + /// The to copy from. public CryptoProviderFactory(CryptoProviderFactory other) { if (other == null) @@ -90,7 +88,7 @@ public CryptoProviderFactory(CryptoProviderFactory other) } /// - /// Gets the + /// Gets the . /// public CryptoProviderCache CryptoProviderCache { get; internal set; } @@ -119,21 +117,21 @@ public int SignatureProviderObjectPoolCacheSize } /// - /// Creates an instance of for a specific <SecurityKey, Algorithm>. + /// Creates an instance of for a specific and . /// - /// the to use. - /// the algorithm to use. - /// thrown if is null. - /// thrown if is null or empty. - /// thrown if and algorithm pair are not supported. - /// thrown if returns a type that is not assignable from . + /// The to use. + /// The algorithm to use. + /// Thrown if is null. + /// Thrown if is null or empty. + /// Thrown if the combination of and is not supported. + /// Thrown if the type returned by is not assignable to . /// - /// If is set and returns true. + /// If is set and returns true, /// is called to obtain the . /// - /// When finished with the call . + /// Once done with the , call . /// - /// an instance of + /// An instance of . public virtual AuthenticatedEncryptionProvider CreateAuthenticatedEncryptionProvider(SecurityKey key, string algorithm) { if (key == null) @@ -158,42 +156,42 @@ public virtual AuthenticatedEncryptionProvider CreateAuthenticatedEncryptionProv } /// - /// Creates an instance of for a specific <SecurityKey, Algorithm>. + /// Creates an instance of for a specific and . /// - /// the to use. - /// the algorithm to use. - /// thrown if is null. - /// thrown if is null or empty. - /// thrown if and algorithm pair are not supported. - /// thrown if returns a type not assignable from . + /// The to use. + /// The algorithm to use. + /// Thrown if is null. + /// Thrown if is null or empty. + /// Thrown if the combination of and is not supported. + /// Thrown if the type returned by is not assignable to . /// - /// If is set and returns true. + /// If is set and returns true, /// is called to obtain the . /// - /// When finished with the call . + /// Once done with the , call . /// - /// an instance of + /// An instance of . public virtual KeyWrapProvider CreateKeyWrapProvider(SecurityKey key, string algorithm) { return CreateKeyWrapProvider(key, algorithm, false); } /// - /// Creates an instance of for a specific <SecurityKey, Algorithm>. + /// Creates an instance of for a specific and . /// - /// the to use. - /// the algorithm to use. - /// thrown if is null. - /// thrown if is null or empty. - /// thrown if and algorithm pair are not supported. - /// thrown if returns a type that is not assignable from . + /// The to use. + /// The algorithm to use. + /// Thrown if is null. + /// Thrown if is null or empty. + /// Thrown if the combination of and is not supported. + /// Thrown if the type returned by is not assignable to . /// - /// If is set and returns true. - /// is called to obtain the . + /// If is set and returns true, + /// is called to obtain the . /// - /// When finished with the call . + /// Once done with the , call . /// - /// an instance of + /// An instance of . public virtual KeyWrapProvider CreateKeyWrapProviderForUnwrap(SecurityKey key, string algorithm) { return CreateKeyWrapProvider(key, algorithm, true); @@ -225,112 +223,115 @@ private KeyWrapProvider CreateKeyWrapProvider(SecurityKey key, string algorithm, } /// - /// Creates a that creates a signature with the algorithm and . + /// Creates a for signing with the specified and . /// - /// the to use for signing. - /// the algorithm to use for signing. - /// thrown if is null. - /// thrown if is null or empty. - /// thrown if is too small. - /// thrown if is not assignable from or . - /// thrown if the key / algorithm is not supported. - /// thrown if returns a type that is not assignable from . + /// The to use for signing. + /// The algorithm to use for signing. + /// Thrown if is null. + /// Thrown if is null or empty. + /// Thrown if is too small. + /// Thrown if is not assignable from or . + /// Thrown if the key or algorithm combination is not supported. + /// Thrown if the type returned by is not assignable to . /// - /// AsymmetricSignatureProviders require access to a PrivateKey for Signing. - /// When finished with the call . - /// If is set and returns true. + /// AsymmetricSignatureProviders require access to a PrivateKey for signing. + /// Once done with the , call . + /// If is set and returns true, /// is called to obtain the . /// /// - /// A that can be used to create a signature using the and algorithm. + /// A instance that can be used to create a signature. public virtual SignatureProvider CreateForSigning(SecurityKey key, string algorithm) { return CreateForSigning(key, algorithm, CacheSignatureProviders); } /// - /// Creates a that creates a signature with the algorithm and . + /// Creates a for signing with the specified and . /// - /// the to use for signing. - /// the algorithm to use for signing. - /// indicates if the should be cached for reuse. - /// thrown if is null. - /// thrown if is null or empty. - /// thrown if is too small. - /// thrown if is not assignable from or . - /// thrown if the key / algorithm is not supported. - /// thrown if returns a type that is not assignable from . + /// The to use for signing. + /// The algorithm to use for signing. + /// Indicates whether the should be cached for reuse. + /// Thrown if is null. + /// Thrown if is null or empty. + /// Thrown if is too small. + /// Thrown if is not assignable from or . + /// Thrown if the combination of and is not supported. + /// Thrown if the type returned by is not assignable to . /// - /// AsymmetricSignatureProviders require access to a PrivateKey for Signing. - /// When finished with the call . - /// If is set and returns true. + /// AsymmetricSignatureProviders require access to a PrivateKey for signing. + /// Once done with the , call . + /// If is set and returns true, /// is called to obtain the . /// /// - /// A that can be used to create a signature using the and algorithm. + /// A instance that can be used to create a signature. public virtual SignatureProvider CreateForSigning(SecurityKey key, string algorithm, bool cacheProvider) { return CreateSignatureProvider(key, algorithm, true, cacheProvider); } /// - /// Creates a that supports the and algorithm. + /// Creates a for verifying signatures with the specified and . /// /// The to use for signature verification. - /// The algorithm to use for verifying. - /// thrown if is null. - /// thrown if is null or empty. - /// thrown if is too small. - /// thrown if is not assignable from or . - /// thrown if the key / algorithm is not supported. - /// thrown if returns a type that is not assignable from . - /// When finished with the call . - /// If is set and returns true. + /// The algorithm to use for verifying signatures. + /// Thrown if is null. + /// Thrown if is null or empty. + /// Thrown if is too small. + /// Thrown if is not assignable from or . + /// Thrown if the combination of and is not supported. + /// Thrown if the type returned by is not assignable to . + /// + /// Once done with the , call . + /// If is set and returns true, /// is called to obtain the . /// /// - /// A that can be used to validate a signature using the and algorithm. + /// A instance that can be used to validate signatures using the and algorithm. public virtual SignatureProvider CreateForVerifying(SecurityKey key, string algorithm) { return CreateForVerifying(key, algorithm, CacheSignatureProviders); } /// - /// Creates a that supports the and algorithm. + /// Creates a for verifying signatures with the specified and . /// /// The to use for signature verification. - /// The algorithm to use for verifying. - /// should the be cached. - /// thrown if is null. - /// thrown if is null or empty. - /// thrown if is too small. - /// thrown if is not assignable from or . - /// thrown if the key / algorithm is not supported. - /// thrown if returns a type that is not assignable from . - /// When finished with the call . - /// If is set and returns true. + /// The algorithm to use for verifying signatures. + /// Specifies whether the should be cached for reuse. + /// Thrown if is null. + /// Thrown if is null or empty. + /// Thrown if is too small. + /// Thrown if is not assignable from or . + /// Thrown if the combination of and is not supported. + /// Thrown if the type returned by is not assignable to . + /// + /// Once done with the , call . + /// If is set and returns true, /// is called to obtain the . /// /// - /// A that can be used to validate a signature using the and algorithm. + /// A instance that can be used to validate signatures using the and algorithm. public virtual SignatureProvider CreateForVerifying(SecurityKey key, string algorithm, bool cacheProvider) { return CreateSignatureProvider(key, algorithm, false, cacheProvider); } /// - /// Creates a for a specific algorithm. + /// Creates a instance for a specific hash algorithm. /// - /// the name of the hash algorithm to create. - /// thrown if is null or empty. - /// thrown if returns a type that is not assignable from . - /// thrown if is not supported. - /// When finished with the call . - /// If is set and returns true. + /// The name of the hash algorithm to create. + /// Thrown if is null or empty. + /// Thrown if returns a type that is not assignable to . + /// Thrown if is not supported. + /// + /// Once done with the , call . + /// If is set and returns true, /// is called to obtain the . /// /// - /// A . + /// A instance that corresponds to the specified . public virtual HashAlgorithm CreateHashAlgorithm(HashAlgorithmName algorithm) { if (CustomCryptoProvider != null && CustomCryptoProvider.IsSupportedAlgorithm(algorithm.Name)) @@ -355,18 +356,19 @@ public virtual HashAlgorithm CreateHashAlgorithm(HashAlgorithmName algorithm) } /// - /// Creates a for a specific algorithm. + /// Creates a instance for a specific hash algorithm. /// - /// the name of the hash algorithm to create. - /// thrown if is null or empty. - /// thrown if returns a type that is not assignable from . - /// thrown if is not supported. - /// When finished with the call . - /// If is set and returns true. + /// The name of the hash algorithm to create. + /// Thrown if is null or empty. + /// Thrown if returns a type that is not assignable to . + /// Thrown if is not supported. + /// + /// Once done with the , call . + /// If is set and returns true, /// is called to obtain the . /// /// - /// A . + /// A instance that corresponds to the specified . public virtual HashAlgorithm CreateHashAlgorithm(string algorithm) { if (string.IsNullOrEmpty(algorithm)) @@ -401,20 +403,21 @@ public virtual HashAlgorithm CreateHashAlgorithm(string algorithm) } /// - /// Returns a for a specific algorithm. + /// Creates a instance for a specific keyed hash algorithm. /// - /// bytes to use to create the Keyed Hash. - /// the name of the keyed hash algorithm to create. - /// thrown if is null. - /// thrown if is null or empty. - /// thrown if returns a type that is not assignable from . - /// is not supported. - /// When finished with the call . - /// If is set and returns true. + /// The bytes to use as the key for the keyed hash. + /// The name of the keyed hash algorithm to create. + /// Thrown if is null. + /// Thrown if is null or empty. + /// Thrown if returns a type that is not assignable to . + /// Thrown if is not supported. + /// + /// Once done with the , call . + /// If is set and returns true, /// is called to obtain the . /// /// - /// A . + /// A instance that corresponds to the specified . public virtual KeyedHashAlgorithm CreateKeyedHashAlgorithm(byte[] keyBytes, string algorithm) { if (keyBytes == null) @@ -615,7 +618,7 @@ private SignatureProvider CreateSignatureProvider(SecurityKey key, string algori /// In these cases, will be an empty string, and these keys should not be cached. /// /// to be examined. - /// True if should be cached, false otherwise. + /// if should be cached; otherwise, . internal static bool ShouldCacheSignatureProvider(SignatureProvider signatureProvider) { _ = signatureProvider ?? throw new ArgumentNullException(nameof(signatureProvider)); @@ -623,16 +626,17 @@ internal static bool ShouldCacheSignatureProvider(SignatureProvider signaturePro } /// - /// Checks if an algorithm is supported. + /// Checks if the specified hash algorithm is supported. /// - /// the name of the Hash algorithm. - /// Only considers known Hash algorithms. - /// true if: - /// - /// If is set and returns true. - /// - /// The algorithm is supported. - /// + /// The name of the hash algorithm. + /// Considers only known hash algorithms. + /// + /// if: + /// + /// is set and returns true, + /// The algorithm is supported. + /// + /// Otherwise, . /// public virtual bool IsSupportedAlgorithm(string algorithm) { @@ -643,21 +647,25 @@ public virtual bool IsSupportedAlgorithm(string algorithm) } /// - /// Checks if the algorithm and is supported. + /// Checks if the specified algorithm and are supported. /// - /// the security algorithm to apply. - /// the . - /// Algorithms are supported for specific key types. + /// The security algorithm to apply. + /// The . + /// + /// Algorithms are supported for specific key types. /// For example: - /// and will return true. - /// and will return false. + /// + /// and will return true. + /// and will return false. + /// /// - /// true if: - /// - /// If is set and returns true. - /// - /// The algorithm / key pair is supported. - /// + /// + /// if: + /// + /// is set and returns true, + /// The algorithm / key pair is supported. + /// + /// Otherwise, . /// public virtual bool IsSupportedAlgorithm(string algorithm, SecurityKey key) { @@ -672,10 +680,10 @@ public virtual bool IsSupportedAlgorithm(string algorithm, SecurityKey key) } /// - /// When finished with a call this method for cleanup. The default behavior is to call + /// Releases resources associated with a instance. The default behavior is to call . /// - /// to be released. - /// thrown if is null. + /// The instance to release. + /// Thrown if is null. public virtual void ReleaseHashAlgorithm(HashAlgorithm hashAlgorithm) { if (hashAlgorithm == null) @@ -687,10 +695,10 @@ public virtual void ReleaseHashAlgorithm(HashAlgorithm hashAlgorithm) } /// - /// When finished with a call this method for cleanup."/> + /// Releases resources associated with a instance. /// - /// to be released. - /// thrown if is null. + /// The instance to release. + /// Thrown if is null. public virtual void ReleaseKeyWrapProvider(KeyWrapProvider provider) { if (provider == null) @@ -702,10 +710,10 @@ public virtual void ReleaseKeyWrapProvider(KeyWrapProvider provider) } /// - /// When finished with a call this method for cleanup."/> + /// Releases resources associated with an instance. /// - /// to be released. - /// thrown if is null. + /// The instance to release. + /// Thrown if is null. public virtual void ReleaseRsaKeyWrapProvider(RsaKeyWrapProvider provider) { if (provider == null) @@ -717,10 +725,10 @@ public virtual void ReleaseRsaKeyWrapProvider(RsaKeyWrapProvider provider) } /// - /// When finished with a call this method for cleanup. The default behavior is to call + /// Releases resources associated with a instance. /// - /// to be released. - /// thrown if is null. + /// The instance to release. + /// Thrown if is null. public virtual void ReleaseSignatureProvider(SignatureProvider signatureProvider) { if (signatureProvider == null) diff --git a/src/Microsoft.IdentityModel.Tokens/Encryption/AuthenticatedEncryptionProvider.cs b/src/Microsoft.IdentityModel.Tokens/Encryption/AuthenticatedEncryptionProvider.cs index b9459a1af8..14a7feb193 100644 --- a/src/Microsoft.IdentityModel.Tokens/Encryption/AuthenticatedEncryptionProvider.cs +++ b/src/Microsoft.IdentityModel.Tokens/Encryption/AuthenticatedEncryptionProvider.cs @@ -39,11 +39,11 @@ private struct AuthenticatedKeys /// /// The that will be used for crypto operations. /// The encryption algorithm to apply. - /// 'key' is null. - /// 'algorithm' is null or whitespace. - /// key size is not large enough. - /// 'algorithm' is not supported. - /// a symmetricSignatureProvider is not created. + /// Thrown if is null. + /// Thrown if is null or whitespace. + /// Thrown if the key size is not large enough. + /// Thrown if is not supported. + /// Thrown if a symmetricSignatureProvider is not created. public AuthenticatedEncryptionProvider(SecurityKey key, string algorithm) { if (key == null) @@ -239,29 +239,30 @@ internal SymmetricSignatureProvider CreateSymmetricSignatureProvider() public SecurityKey Key { get; } /// - /// Encrypts the 'plaintext' + /// Encrypts the specified plaintext. /// - /// the data to be encrypted. - /// will be combined with iv and ciphertext to create an authenticationtag. - /// containing ciphertext, iv, authenticationtag. - /// plaintext is null or empty. - /// authenticationData is null or empty. - /// AES crypto operation threw. See inner exception for details. + /// The data to be encrypted. + /// Will be combined with the initialization vector and ciphertext to create an authentication tag. + /// A the containing ciphertext, initialization vector, the and authentication tag. + /// Thrown if is null or empty. + /// Thrown if is null or empty. + /// Thrown if AES crypto operation threw. See inner exception for details. + /// Thrown if the internal is disposed. public virtual AuthenticatedEncryptionResult Encrypt(byte[] plaintext, byte[] authenticatedData) { return Encrypt(plaintext, authenticatedData, null); } /// - /// Encrypts the 'plaintext' + /// Encrypts the specified plaintext. /// - /// the data to be encrypted. - /// will be combined with iv and ciphertext to create an authenticationtag. - /// initialization vector for encryption. - /// containing ciphertext, iv, authenticationtag. - /// is null or empty. - /// is null or empty. - /// Thrown if the AES crypto operation threw. See inner exception for details. + /// The data to be encrypted. + /// The initialization vector to be used with the encryption algorithm. + /// Will be combined with the initialization vector and ciphertext to create an authentication tag. + /// A containing the ciphertext, initialization vector, and the authentication tag. + /// Thrown if is null or empty. + /// Thrown if is null or empty. + /// Thrown if AES crypto operation threw. See inner exception for details. /// Thrown if the internal is disposed. public virtual AuthenticatedEncryptionResult Encrypt(byte[] plaintext, byte[] authenticatedData, byte[] iv) { @@ -278,19 +279,19 @@ public virtual AuthenticatedEncryptionResult Encrypt(byte[] plaintext, byte[] au } /// - /// Decrypts ciphertext into plaintext + /// Decrypts ciphertext into plaintext. /// - /// the encrypted text to decrypt. - /// the authenticateData that is used in verification. - /// the initialization vector used when creating the ciphertext. - /// the authenticationTag that was created during the encyption. - /// decrypted ciphertext - /// is null or empty. - /// is null or empty. - /// is null or empty. - /// is null or empty. + /// The encrypted text to be decrypted. + /// The authenticate data that is used in verification. + /// The initialization vector used when creating the ciphertext. + /// The authentication tag that was created during the encyption. + /// The decrypted ciphertext. + /// Thrown if is null or empty. + /// Thrown if is null or empty. + /// Thrown if is null or empty. + /// Thrown if is null or empty. /// Thrown if the signature over the authenticationTag fails to verify. - /// Thrown if the AES crypto operation threw. See inner exception. + /// Thrown if the AES crypto operation threw. See inner exception for details. /// Thrown if the internal is disposed. public virtual byte[] Decrypt(byte[] ciphertext, byte[] authenticatedData, byte[] iv, byte[] authenticationTag) { @@ -347,11 +348,11 @@ protected virtual void Dispose(bool disposing) } /// - /// Checks if an 'key, algorithm' pair is supported + /// Checks if the key/algorithm pair is supported. /// - /// the - /// the algorithm to check. - /// true if 'key, algorithm' pair is supported. + /// The . + /// The algorithm to check. + /// if the key/algorithm pair is supported. protected virtual bool IsSupportedAlgorithm(SecurityKey key, string algorithm) { return SupportedAlgorithms.IsSupportedEncryptionAlgorithm(algorithm, key); @@ -385,8 +386,8 @@ private AuthenticatedKeys GetAlgorithmParameters(SecurityKey key, string algorit /// The algorithm parameter logically defines a HMAC algorithm. /// This method returns the HMAC to use. /// - /// - /// + /// The name of the algorithm for HMAC. + /// The name of the HMAC algorithm. private static string GetHmacAlgorithm(string algorithm) { if (SecurityAlgorithms.Aes128CbcHmacSha256.Equals(algorithm)) @@ -402,15 +403,15 @@ private static string GetHmacAlgorithm(string algorithm) } /// - /// Called to obtain the byte[] needed to create a + /// Called to obtain the byte[] needed to create a . /// - /// that will be used to obtain the byte[]. + /// The that will be used to obtain the byte[]. /// [] that is used to populated the KeyedHashAlgorithm. - /// if is null. - /// if a byte[] can not be obtained from SecurityKey. + /// Thrown if is null. + /// Thrown if a byte[] can not be obtained from SecurityKey. /// and are supported. - /// For a .Key is returned - /// For a Base64UrlEncoder.DecodeBytes is called with if == JsonWebAlgorithmsKeyTypes.Octet + /// For a , is returned + /// For a , is called with if == JsonWebAlgorithmsKeyTypes.Octet. /// protected virtual byte[] GetKeyBytes(SecurityKey key) { @@ -443,13 +444,13 @@ internal static byte[] Transform(ICryptoTransform transform, byte[] input, int i } /// - /// Checks that the key has sufficient length + /// Checks that the key has sufficient length. /// - /// that contains bytes. - /// the algorithm to apply. - /// if is null. - /// if is null or empty. - /// if is not a supported algorithm. + /// The that contains bytes. + /// The algorithm to apply. + /// Thrown if is null. + /// Thrown if is null or empty. + /// Thrown if is not a supported algorithm. protected virtual void ValidateKeySize(SecurityKey key, string algorithm) { if (key == null) diff --git a/src/Microsoft.IdentityModel.Tokens/Encryption/AuthenticatedEncryptionResult.cs b/src/Microsoft.IdentityModel.Tokens/Encryption/AuthenticatedEncryptionResult.cs index 6030278082..98f67dbc78 100644 --- a/src/Microsoft.IdentityModel.Tokens/Encryption/AuthenticatedEncryptionResult.cs +++ b/src/Microsoft.IdentityModel.Tokens/Encryption/AuthenticatedEncryptionResult.cs @@ -9,12 +9,12 @@ namespace Microsoft.IdentityModel.Tokens public class AuthenticatedEncryptionResult { /// - /// Initializes a new + /// Initializes a new instance of the class. /// - /// the used during - /// protected text. - /// the initialization vector used. - /// the bytes that need be passed to . + /// The used during . + /// The encrypted text. + /// The initialization vector used. + /// The authentication tag that was created during the encyption and needs . public AuthenticatedEncryptionResult(SecurityKey key, byte[] ciphertext, byte[] iv, byte[] authenticationTag) { Key = key; @@ -39,7 +39,7 @@ public AuthenticatedEncryptionResult(SecurityKey key, byte[] ciphertext, byte[] public byte[] IV { get; private set; } /// - /// Gets the authentication tag + /// Gets the authentication tag. /// public byte[] AuthenticationTag { get; private set; } } diff --git a/src/Microsoft.IdentityModel.Tokens/Encryption/KeyWrapProvider.cs b/src/Microsoft.IdentityModel.Tokens/Encryption/KeyWrapProvider.cs index 4de8eb217c..fd3d009afe 100644 --- a/src/Microsoft.IdentityModel.Tokens/Encryption/KeyWrapProvider.cs +++ b/src/Microsoft.IdentityModel.Tokens/Encryption/KeyWrapProvider.cs @@ -6,7 +6,7 @@ namespace Microsoft.IdentityModel.Tokens { /// - /// Provides Wrap key and Unwrap key services. + /// Provides Wrap and Unwrap key services. /// public abstract class KeyWrapProvider : IDisposable { @@ -27,7 +27,7 @@ public abstract class KeyWrapProvider : IDisposable public abstract SecurityKey Key { get; } /// - /// Calls and + /// Calls and . /// public void Dispose() { @@ -36,23 +36,23 @@ public void Dispose() } /// - /// Can be over written in descendants to dispose of internal components. + /// Can be overridden in descendants to dispose of internal components. /// - /// true, if called from Dispose(), false, if invoked inside a finalizer + /// true if called from Dispose(), false if invoked inside a finalizer. protected abstract void Dispose(bool disposing); /// - /// Unwrap a key. + /// Unwraps a key. /// - /// key to unwrap. - /// Unwrapped key. + /// The key to unwrap. + /// The unwrapped key. public abstract byte[] UnwrapKey(byte[] keyBytes); /// - /// Wrap a key. + /// Wraps a key. /// - /// the key to be wrapped - /// wrapped key. + /// The key to be wrapped. + /// The wrapped key. public abstract byte[] WrapKey(byte[] keyBytes); } } diff --git a/src/Microsoft.IdentityModel.Tokens/Encryption/RsaKeyWrapProvider.cs b/src/Microsoft.IdentityModel.Tokens/Encryption/RsaKeyWrapProvider.cs index c438446739..f041fde821 100644 --- a/src/Microsoft.IdentityModel.Tokens/Encryption/RsaKeyWrapProvider.cs +++ b/src/Microsoft.IdentityModel.Tokens/Encryption/RsaKeyWrapProvider.cs @@ -16,17 +16,17 @@ public class RsaKeyWrapProvider : KeyWrapProvider private bool _willUnwrap; /// - /// Initializes a new instance of used for wrapping and un-wrappping keys. - /// These keys are usually symmetric session keys that are wrapped using the recipients public key. + /// Initializes a new instance of the class used for wrapping and unwrapping keys. + /// These keys are usually symmetric session keys that are wrapped using the recipient's public key. + /// /// The that will be used for cryptographic operations. /// The KeyWrap algorithm to apply. - /// Whether this is required to un-wrap keys. If true, the private key is required. - /// 'key' is null. - /// 'algorithm' is null. - /// The key size doesn't match the algorithm. - /// If and algorithm pair are not supported. - /// Failed to create RSA algorithm with provided key and algorithm. - /// + /// Whether this is required to unwrap keys. If true, the private key is required. + /// Thrown if is null. + /// Thrown if is null. + /// Thrown if the key size doesn't match the algorithm. + /// Thrown if the and pair are not supported. + /// Thrown if failed to create RSA algorithm with the provided key and algorithm. public RsaKeyWrapProvider(SecurityKey key, string algorithm, bool willUnwrap) { if (key == null) @@ -82,9 +82,9 @@ protected override void Dispose(bool disposing) } /// - /// Checks if an algorithm is supported. + /// Checks if the specified algorithm is supported. /// - /// The that will be used for crypto operations. + /// The that will be used for cryptographic operations. /// The KeyWrap algorithm to apply. /// true if the algorithm is supported; otherwise, false. protected virtual bool IsSupportedAlgorithm(SecurityKey key, string algorithm) @@ -93,14 +93,14 @@ protected virtual bool IsSupportedAlgorithm(SecurityKey key, string algorithm) } /// - /// Unwrap a key using RSA decryption. + /// Unwraps a key using RSA decryption. /// - /// the bytes to unwrap. - /// Unwrapped key - /// 'keyBytes' is null or length == 0. - /// If has been called. - /// Failed to unwrap the wrappedKey. - /// If the internal RSA algorithm is null. + /// The bytes to unwrap. + /// The unwrapped key. + /// Thrown if is null or has a length of 0. + /// Thrown if has been called. + /// Thrown if the key unwrapping operation fails. + /// Thrown if the internal RSA algorithm is null. public override byte[] UnwrapKey(byte[] keyBytes) { if (keyBytes == null || keyBytes.Length == 0) @@ -120,14 +120,14 @@ public override byte[] UnwrapKey(byte[] keyBytes) } /// - /// Wrap a key using RSA encryption. + /// Wraps a key using RSA encryption. /// - /// the key to be wrapped - /// A wrapped key - /// 'keyBytes' is null or has length == 0. - /// If has been called. - /// Failed to wrap the 'keyBytes'. - /// If the internal RSA algorithm is null. + /// The key to be wrapped. + /// A wrapped key. + /// Thrown if is null or has a length of 0. + /// Thrown if has been called. + /// Thrown if the key wrapping operation fails. + /// Thrown if the internal RSA algorithm is null. public override byte[] WrapKey(byte[] keyBytes) { if (keyBytes == null || keyBytes.Length == 0) diff --git a/src/Microsoft.IdentityModel.Tokens/Encryption/SymmetricKeyWrapProvider.cs b/src/Microsoft.IdentityModel.Tokens/Encryption/SymmetricKeyWrapProvider.cs index e142e3a338..6ee8cb90b5 100644 --- a/src/Microsoft.IdentityModel.Tokens/Encryption/SymmetricKeyWrapProvider.cs +++ b/src/Microsoft.IdentityModel.Tokens/Encryption/SymmetricKeyWrapProvider.cs @@ -8,7 +8,7 @@ namespace Microsoft.IdentityModel.Tokens { /// - /// Provides Wrap key and Unwrap key services. + /// Provides Wrap and Unwrap key services. /// public class SymmetricKeyWrapProvider : KeyWrapProvider { @@ -24,16 +24,16 @@ public class SymmetricKeyWrapProvider : KeyWrapProvider private bool _disposed; /// - /// Initializes a new instance of the class used for wrap key and unwrap key. - /// The that will be used for crypto operations. - /// The KeyWrap algorithm to apply. - /// 'key' is null. - /// 'algorithm' is null. - /// If and algorithm pair are not supported. - /// The cannot be converted to byte array - /// The keysize doesn't match the algorithm. - /// Failed to create symmetric algorithm with provided key and algorithm. + /// Initializes a new instance of the class used for wrapping and unwrapping keys. /// + /// The that will be used for cryptographic operations. + /// The KeyWrap algorithm to apply. + /// Thrown if is null. + /// Thrown if is null. + /// Thrown if the and algorithm pair are not supported. + /// Thrown if the cannot be converted to a byte array. + /// Thrown if the key size doesn't match the algorithm. + /// Thrown if failed to create a symmetric algorithm with the provided key and algorithm. public SymmetricKeyWrapProvider(SecurityKey key, string algorithm) { if (key == null) @@ -125,10 +125,12 @@ private static byte[] GetBytes(ulong i) /// /// Returns the . /// - /// - /// The cannot be converted to byte array - /// The keysize doesn't match the algorithm. - /// Failed to create symmetric algorithm with provided key and algorithm. + /// The that will be used for cryptographic operations. + /// The algorithm to apply. + /// The initialized . + /// Thrown if the cannot be converted to a byte array. + /// Thrown if the key size doesn't match the algorithm. + /// Thrown if failed to create a symmetric algorithm with the provided key and algorithm. protected virtual SymmetricAlgorithm GetSymmetricAlgorithm(SecurityKey key, string algorithm) { if (key == null) @@ -175,10 +177,10 @@ protected virtual SymmetricAlgorithm GetSymmetricAlgorithm(SecurityKey key, stri } /// - /// Answers if an algorithm is supported + /// Determines if a specified algorithm is supported. /// - /// the - /// the algorithm to use + /// The to use for cryptographic operations. + /// The algorithm to check for support. /// true if the algorithm is supported; otherwise, false. protected virtual bool IsSupportedAlgorithm(SecurityKey key, string algorithm) { @@ -186,14 +188,14 @@ protected virtual bool IsSupportedAlgorithm(SecurityKey key, string algorithm) } /// - /// Unwrap a key using Symmetric decryption. + /// Unwraps a key using symmetric decryption. /// - /// bytes to unwrap - /// Unwraped key - /// 'keyBytes' is null or length == 0. - /// 'keyBytes' is not a multiple of 8. - /// If has been called. - /// Failed to unwrap the wrappedKey. + /// The bytes to unwrap. + /// The unwrapped key. + /// Thrown if is null or has a length of 0. + /// Thrown if is not a multiple of 8. + /// Thrown if has been called. + /// Thrown if the key unwrapping operation fails. public override byte[] UnwrapKey(byte[] keyBytes) { if (keyBytes == null || keyBytes.Length == 0) @@ -341,14 +343,14 @@ private void ValidateKeySize(byte[] key, string algorithm) } /// - /// Wrap a key using Symmetric encryption. + /// Wraps a key using symmetric encryption. /// - /// the key to be wrapped - /// The wrapped key result - /// 'keyBytes' is null or has length 0. - /// 'keyBytes' is not a multiple of 8. - /// If has been called. - /// Failed to wrap 'keyBytes'. + /// The key to be wrapped. + /// The wrapped key. + /// Thrown if is null or has a length of 0. + /// Thrown if is not a multiple of 8. + /// Thrown if has been called. + /// Thrown if the key wrapping operation fails. public override byte[] WrapKey(byte[] keyBytes) { if (keyBytes == null || keyBytes.Length == 0) diff --git a/src/Microsoft.IdentityModel.Tokens/Json/JsonSerializerPrimitives.cs b/src/Microsoft.IdentityModel.Tokens/Json/JsonSerializerPrimitives.cs index e8e9590eb4..1b9e63ed60 100644 --- a/src/Microsoft.IdentityModel.Tokens/Json/JsonSerializerPrimitives.cs +++ b/src/Microsoft.IdentityModel.Tokens/Json/JsonSerializerPrimitives.cs @@ -28,14 +28,14 @@ internal static class JsonSerializerPrimitives internal static string False = "false"; /// - /// Creates a JsonException that provides information on what went wrong + /// Creates a that provides information on what went wrong. /// - /// the . - /// the type the reader was expecting to find. - /// the name of the type being read. - /// the property name being read. - /// inner exception if any. - /// + /// The instance. + /// The expected type the reader was looking for. + /// The name of the type being read. + /// The property name being read. + /// The optional inner exception if available. + /// A instance. public static JsonException CreateJsonReaderException( ref Utf8JsonReader reader, string expectedType, @@ -591,7 +591,6 @@ internal static JsonElement ReadJsonElement(ref Utf8JsonReader reader) internal static List ReadArrayOfObjects(ref Utf8JsonReader reader, string propertyName, string className) { - // returning null keeps the same logic as JsonSerialization.ReadObject if (IsReaderPositionedOnNull(ref reader, false, true)) return null; @@ -679,13 +678,13 @@ internal static string ReadStringAsBool(ref Utf8JsonReader reader, string proper } /// - /// This method allows a JsonTokenType to be string or number but, it will always return it as a string. + /// Reads a JSON token value from a , treating it as a string regardless of its actual type (string or number). /// - /// The - /// The property name that is being read. - /// The type that is being deserialized. - /// If true reader.Read() will be called. - /// Value from reader as string. + /// The instance. + /// The property name being read. + /// The type being deserialized. + /// If true, the reader will advance to the next token using . + /// The JSON token value as a string. internal static string ReadStringOrNumberAsString(ref Utf8JsonReader reader, string propertyName, string className, bool read = false) { // returning null keeps the same logic as JsonSerialization.ReadObject @@ -952,14 +951,13 @@ internal static void ReadStringsSkipNulls( } /// - /// This method is called when deserializing a property value as an object. - /// Normally, we put the object into a Dictionary[string, object]. + /// Reads a property value from a as an object during deserialization. /// - /// The - /// The property name that is being read. - /// The type that is being deserialized. - /// If true reader.Read() will be called. - /// Value from reader as an object. + /// The instance. + /// The property name being read. + /// The type being deserialized. + /// If true, the reader will advance to the next token using . + /// The property value from the reader as an object. internal static object ReadPropertyValueAsObject(ref Utf8JsonReader reader, string propertyName, string className, bool read = false) { // The parameter 'read' can be used by callers reader position the reader to the next token. @@ -1089,10 +1087,10 @@ public static void WriteObjects(ref Utf8JsonWriter writer, IDictionary - /// Writes an 'object' as a JsonProperty. + /// Writes an object as a . /// This was written to support what IdentityModel6x supported and is not meant to be a /// general object serializer. - /// If a user needs to serialize a special value, then serialize the value into a JsonElement. + /// If a user needs to serialize a special value, then serialize the value into a . /// public static void WriteObject(ref Utf8JsonWriter writer, string key, object obj) {