From 58667e733437aeed5342f8233a4118a43b7ae319 Mon Sep 17 00:00:00 2001 From: Krzysztof Wicher Date: Fri, 20 Nov 2020 21:32:07 +0100 Subject: [PATCH] Add missing XML docs to System.Security.* (#44461) * Add missing XML docs to System.Security.* * add missing < * Apply suggestions from code review Co-authored-by: Carlos Sanchez <1175054+carlossanlop@users.noreply.github.com> * Update src/libraries/System.Security.Cryptography.Pkcs/src/System/Security/Cryptography/Pkcs/Rfc3161TimestampTokenInfo.cs Co-authored-by: Carlos Sanchez <1175054+carlossanlop@users.noreply.github.com> * apply feedback * fix merge conflict (renamed parameters) * Apply suggestions from code review Co-authored-by: Jeremy Barton * Update src/libraries/System.Security.Cryptography.Pkcs/src/System/Security/Cryptography/Pkcs/Rfc3161TimestampTokenInfo.cs Co-authored-by: Carlos Sanchez <1175054+carlossanlop@users.noreply.github.com> Co-authored-by: Jeremy Barton --- .../Security/Cryptography/Rfc2898DeriveBytes.cs | 3 + .../Cryptography/Pkcs/Rfc3161TimestampTokenInfo.cs | 98 ++++++++++++++++++++++ 2 files changed, 101 insertions(+) diff --git a/src/libraries/System.Security.Cryptography.Algorithms/src/System/Security/Cryptography/Rfc2898DeriveBytes.cs b/src/libraries/System.Security.Cryptography.Algorithms/src/System/Security/Cryptography/Rfc2898DeriveBytes.cs index 395a423..b6e615e 100644 --- a/src/libraries/System.Security.Cryptography.Algorithms/src/System/Security/Cryptography/Rfc2898DeriveBytes.cs +++ b/src/libraries/System.Security.Cryptography.Algorithms/src/System/Security/Cryptography/Rfc2898DeriveBytes.cs @@ -27,6 +27,9 @@ namespace System.Security.Cryptography private int _startIndex; private int _endIndex; + /// + /// Gets the hash algorithm used for byte derivation. + /// public HashAlgorithmName HashAlgorithm { get; } public Rfc2898DeriveBytes(byte[] password, byte[] salt, int iterations) diff --git a/src/libraries/System.Security.Cryptography.Pkcs/src/System/Security/Cryptography/Pkcs/Rfc3161TimestampTokenInfo.cs b/src/libraries/System.Security.Cryptography.Pkcs/src/System/Security/Cryptography/Pkcs/Rfc3161TimestampTokenInfo.cs index 5f29d71..bd514cc 100644 --- a/src/libraries/System.Security.Cryptography.Pkcs/src/System/Security/Cryptography/Pkcs/Rfc3161TimestampTokenInfo.cs +++ b/src/libraries/System.Security.Cryptography.Pkcs/src/System/Security/Cryptography/Pkcs/Rfc3161TimestampTokenInfo.cs @@ -12,6 +12,9 @@ using Internal.Cryptography; namespace System.Security.Cryptography.Pkcs { + /// + /// Represents the timestamp token information class defined in RFC3161 as TSTInfo. + /// public sealed class Rfc3161TimestampTokenInfo { private readonly byte[] _encodedBytes; @@ -20,6 +23,21 @@ namespace System.Security.Cryptography.Pkcs private Oid? _hashAlgorithmId; private ReadOnlyMemory? _tsaNameBytes; + /// + /// Initializes a new instance of the class with the specified parameters. + /// + /// An OID representing the TSA's policy under which the response was produced. + /// A hash algorithm OID of the data to be timestamped. + /// A hash value of the data to be timestamped. + /// An integer assigned by the TSA to the . + /// The timestamp encoded in the token. + /// The accuracy with which is compared. Also see . + /// to ensure that every timestamp token from the same TSA can always be ordered based on the , regardless of the accuracy; to make indicate when token has been created by the TSA. + /// The nonce associated with this timestamp token. Using a nonce always allows to detect replays, and hence its use is recommended. + /// The hint in the TSA name identification. The actual identification of the entity that signed the response will always occur through the use of the certificate identifier. + /// The extension values associated with the timestamp. + /// If , , or are present in the , then the same value should be used. If is not provided, then the accuracy may be available through other means such as i.e. . + /// ASN.1 corrupted data. public Rfc3161TimestampTokenInfo( Oid policyId, Oid hashAlgorithmId, @@ -57,17 +75,76 @@ namespace System.Security.Cryptography.Pkcs _parsedData = tstInfo; } + /// + /// Gets the version of the timestamp token. + /// + /// The version of the timestamp token. public int Version => _parsedData.Version; + + /// + /// Gets an OID representing the TSA's policy under which the response was produced. + /// + /// An OID representing the TSA's policy under which the response was produced. public Oid PolicyId => (_policyOid ??= new Oid(_parsedData.Policy, null)); + + /// + /// Gets an OID of the hash algorithm. + /// + /// An OID of the hash algorithm. public Oid HashAlgorithmId => (_hashAlgorithmId ??= new Oid(_parsedData.MessageImprint.HashAlgorithm.Algorithm, null)); + + /// + /// Gets the data representing the message hash. + /// + /// The data representing the message hash. public ReadOnlyMemory GetMessageHash() => _parsedData.MessageImprint.HashedMessage; + + /// + /// Gets an integer assigned by the TSA to the . + /// + /// An integer assigned by the TSA to the . public ReadOnlyMemory GetSerialNumber() => _parsedData.SerialNumber; + + /// + /// Gets the timestamp encoded in the token. + /// + /// The timestamp encoded in the token. public DateTimeOffset Timestamp => _parsedData.GenTime; + + /// + /// Gets the accuracy with which is compared. + /// + /// + /// The accuracy with which is compared. public long? AccuracyInMicroseconds => _parsedData.Accuracy?.TotalMicros; + + /// + /// Gets a value indicating if every timestamp token from the same TSA can always be ordered based on the , regardless of the accuracy; If , indicates when the token has been created by the TSA. + /// + /// A value indicating if every timestamp token from the same TSA can always be ordered based on the . public bool IsOrdering => _parsedData.Ordering; + + /// + /// Gets the nonce associated with this timestamp token. + /// + /// The nonce associated with this timestamp token. public ReadOnlyMemory? GetNonce() => _parsedData.Nonce; + + /// + /// Gets a value indicating whether there are any extensions associated with this timestamp token. + /// + /// A value indicating whether there are any extensions associated with this timestamp token. public bool HasExtensions => _parsedData.Extensions?.Length > 0; + /// + /// Gets the data representing the hint in the TSA name identification. + /// + /// The data representing the hint in the TSA name identification. + /// + /// The actual identification of the entity that signed the response + /// will always occur through the use of the certificate identifier (ESSCertID Attribute) + /// inside a SigningCertificate attribute which is part of the signer info. + /// public ReadOnlyMemory? GetTimestampAuthorityName() { if (_tsaNameBytes == null) @@ -88,6 +165,10 @@ namespace System.Security.Cryptography.Pkcs return _tsaNameBytes.Value; } + /// + /// Gets the extension values associated with the timestamp. + /// + /// The extension values associated with the timestamp. public X509ExtensionCollection GetExtensions() { var coll = new X509ExtensionCollection(); @@ -115,11 +196,21 @@ namespace System.Security.Cryptography.Pkcs return coll; } + /// + /// Encodes this object into a TSTInfo value + /// + /// The encoded TSTInfo value. public byte[] Encode() { return _encodedBytes.CloneByteArray(); } + /// + /// Attempts to encode this object as a TSTInfo value, writing the result into the provided buffer. + /// + /// The destination buffer. + /// When this method returns , contains the bytes written to the buffer. + /// if the operation succeeded; if the buffer size was insufficient. public bool TryEncode(Span destination, out int bytesWritten) { if (destination.Length < _encodedBytes.Length) @@ -133,6 +224,13 @@ namespace System.Security.Cryptography.Pkcs return true; } + /// + /// Decodes an encoded TSTInfo value. + /// + /// The input or source buffer. + /// When this method returns , the decoded data. When this method returns , the value is , meaning the data could not be decoded. + /// The number of bytes used for decoding. + /// if the operation succeeded; otherwise. public static bool TryDecode( ReadOnlyMemory encodedBytes, [NotNullWhen(true)] out Rfc3161TimestampTokenInfo? timestampTokenInfo, -- 2.7.4