Writing XMLDocs

Author: colibrishin

Libplanet.Tests/Crypto/BlsPublicKeyTest.cs

@@ -5,6 +5,7 @@
 using Libplanet.Crypto;
 using Xunit;
 using Xunit.Abstractions;
+using CryptoConfig = Libplanet.Crypto.CryptoConfig;
 
 namespace Libplanet.Tests.Crypto
 {
@@ -158,6 +159,8 @@ public void InvalidProofOfPossession()
         [Fact]
         public void Verify()
         {
+            // TEST NEEDED: Does the infinite public key and infinite signature verification return
+            // true?
             var pubKey = new BlsPublicKey(_key1, new BlsSignature(_key1ProofOfPossession));
             var signature = new byte[]
             {

Libplanet/Crypto/BlsPrivateKey.cs

@@ -9,14 +9,34 @@
 
 namespace Libplanet.Crypto
 {
-    public class BlsPrivateKey : IEquatable<BlsPrivateKey>, IECPrivateKey
+    /// <summary>
+    /// A secret key pair of
+    /// <a href="https://datatracker.ietf.org/doc/draft-irtf-cfrg-bls-signature/">BLS Signature</a>
+    /// used in consensus for signing signature.
+    /// It can create <see cref="BlsSignature"/>, which can be verified corresponding
+    /// <see cref="Libplanet.Crypto.BlsPublicKey"/> with message. Also <see cref="BlsSignature"/>
+    /// can be aggregated with another signatures, and can be verified with multiple corresponding
+    /// <see cref="Libplanet.Crypto.BlsPublicKey"/> by <see cref="BlsSignature.AggregateVerify"/>,
+    /// <see cref="BlsSignature.FastAggregateVerify"/> or <see cref="BlsSignature.MultiVerify"/>
+    /// for its use-case. The implementation uses the BLS12_381 curve type with minimal public key
+    /// size setting, which is the same configuration with Ethereum 2.0 Phase 0.
+    /// </summary>
+    /// <remarks>
+    /// These (and any derived representations, e.g., <see cref="ByteArray"/>)
+    /// must be kept secret, if they are exposed, an attacker will be able to
+    /// forge signatures.
+    /// <para>Every <see cref="PrivateKey"/> object is immutable.</para>
+    /// </remarks>
+    /// <seealso cref="Libplanet.Crypto.BlsPublicKey"/>
+    public sealed class BlsPrivateKey : IEquatable<BlsPrivateKey>, IECPrivateKey
     {
         private const int KeyByteSize = BLS.SECRETKEY_SERIALIZE_SIZE;
         private readonly IReadOnlyList<byte> _privateKey;
         private BlsPublicKey? _publicKey;
 
         /// <summary>
-        /// Instantiates a new random <see cref="BlsPrivateKey"/>.
+        /// Instantiates a new random <see cref="BlsPrivateKey"/> with CSPRNG (Cryptographically
+        /// Secure Random Number Generator).
         /// </summary>
         public BlsPrivateKey()
         {
@@ -28,6 +48,8 @@ public BlsPrivateKey()
         /// </summary>
         /// <param name="privateKey">A <see cref="byte"/> array representation of private key.
         /// </param>
+        /// <exception cref="ArgumentNullException">Thrown if given value is
+        /// <see cref="ImmutableArray{T}"/> and empty.</exception>
         /// <exception cref="ArgumentOutOfRangeException">Thrown if given private key is not
         /// <see cref="KeyByteSize"/>.
         /// </exception>
@@ -64,7 +86,7 @@ public BlsPrivateKey(string hex)
         }
 
         /// <summary>
-        /// A pair public key of this private key.
+        /// A pair public key of private key.
         /// </summary>
         public BlsPublicKey PublicKey
         {
@@ -83,9 +105,29 @@ public BlsPublicKey PublicKey
 
         IReadOnlyList<byte> IECPrivateKey.KeyBytes => ByteArray;
 
+        /// <summary>
+        /// The parameter for BLS private key signature. This is not supported.
+        /// </summary>
+        /// <exception cref="NotSupportedException">This is not supported.</exception>
         public ECPrivateKeyParameters KeyParam => throw new NotSupportedException(
             "Currently setting key with BLS key parameter is not supported.");
 
+        /// <summary>
+        /// An encoded <see cref="byte"/> array representation.
+        /// </summary>
+        /// <remarks>
+        /// An encoded <see cref="byte"/> array representation can be recovered to a <see
+        /// cref="BlsPrivateKey"/> instance again using
+        /// <see cref="BlsPrivateKey(IReadOnlyList{byte})"/> constructor.
+        /// <para>As like <see cref="BlsPrivateKey"/> instances, it also must be kept secret.
+        /// In practice, this must not be sent over the network, and be securely stored in the file
+        /// system.
+        /// </para>
+        /// <para>To get a mutable array instead of immutable one, use <see cref="ToByteArray()"/>
+        /// method instead.</para>
+        /// </remarks>
+        /// <seealso cref="ToByteArray()"/>
+        /// <seealso cref="PrivateKey(IReadOnlyList{byte})"/>
         [Pure]
         public ImmutableArray<byte> ByteArray => _privateKey.ToImmutableArray();
 
@@ -95,10 +137,37 @@ public BlsPublicKey PublicKey
         public static bool operator !=(BlsPrivateKey left, BlsPrivateKey right) =>
             !left.Equals(right);
 
+        /// <summary>
+        /// Creates a <see cref="BlsPrivateKey"/> instance from hexadecimal string of bytes.
+        /// </summary>
+        /// <param name="hex">A hexadecimal string of a private key's
+        /// <see cref="ByteArray"/>.</param>
+        /// <returns>A created <see cref="BlsPrivateKey"/> instance.</returns>
+        /// <exception cref="ArgumentNullException">Thrown when the given <paramref name="hex"/>
+        /// string is <c>null</c>.</exception>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown when the length of the given
+        /// <paramref name="hex"/> string is too short or too long.</exception>
+        /// <exception cref="FormatException">Thrown when the given <paramref name="hex"/> string is
+        /// not a valid hexadecimal string.</exception>
+        /// <exception cref="CryptographicException">Thrown if deserialization has been failed
+        /// in library.
+        /// </exception>
         [Pure]
         public static BlsPrivateKey FromString(string hex) =>
             new BlsPrivateKey(GenerateBytesFromHexString(hex));
 
+        /// <summary>
+        /// Returns the corresponding Proof of Possession. Public key can be aggregated, therefore
+        /// some public key are not the true public key from a private key.
+        /// <para>The Proof of Possession
+        /// is used for validate whether the public key is derived from a private key.
+        /// </para>
+        /// </summary>
+        /// <returns>Returns the proof of possession of <see cref="BlsPrivateKey"/>.</returns>
+        /// <remarks>The infinite public key (e.g., derived from zero private key) cannot be
+        /// validated with Proof of possession of its infinite signature and considered invalid.
+        /// Therefore, the infinite public key also can be filtered with proof of possession.
+        /// </remarks>
         [Pure]
         public BlsSignature GetProofOfPossession() => PublicKey.ProofOfPossession;
 
@@ -109,14 +178,74 @@ public bool Equals(BlsPrivateKey? other) =>
 
         public override int GetHashCode() => ByteUtil.CalculateHashCode(ToByteArray());
 
+        /// <summary>
+        /// Creates a signature from the given <paramref name="message"/>.
+        /// <para>A created signature can be verified by the corresponding
+        /// <see cref="BlsPublicKey"/>.
+        /// </para>
+        /// <para>Signatures can be created by only the <see cref="BlsPrivateKey"/> which
+        /// corresponds a <see cref="BlsPublicKey"/> to verify these signatures.</para>
+        /// <para>To sum up, a signature is used to guarantee:</para>
+        /// <list type="bullet">
+        /// <item><description>that the <paramref name="message"/> was created by someone possessing
+        /// the corresponding <see cref="BlsPrivateKey"/>,</description></item>
+        /// <item><description>that the possessor cannot deny having sent the
+        /// <paramref name="message"/>, and</description></item>
+        /// <item><description>that the <paramref name="message"/> was not forged in the middle of
+        /// transit.</description></item>
+        /// </list>
+        /// <see cref="BlsSignature"/> can be aggregated, and can verify multiple signature in
+        /// batch.
+        /// <list type="bullet">
+        /// <item><description>If the messages are all different, use
+        /// <see cref="BlsSignature.AggregateVerify"/> or,</description></item>
+        /// <item><description>all the messages are same, use
+        /// <see cref="BlsSignature.FastAggregateVerify"/></description></item>
+        /// <item><description>if
+        /// above all cases are not true, then use <see cref="BlsSignature.MultiVerify"/> without a
+        /// signature aggregation.</description></item>
+        /// </list>
+        /// </summary>
+        /// <param name="message">A message <see cref="byte"/>s to sign.</param>
+        /// <returns>A signature that proves the authenticity of the <paramref name="message"/>.
+        /// It can be verified using <see cref="Libplanet.Crypto.BlsPublicKey.Verify"/>,
+        /// <see cref="BlsSignature.AggregateVerify"/>,
+        /// <see cref="BlsSignature.FastAggregateVerify"/>, or
+        /// <see cref="BlsSignature.MultiVerify"/> method with requiring use-case.
+        /// </returns>
+        /// <seealso cref="Libplanet.Crypto.BlsPublicKey.Verify"/>
+        /// <seealso cref="BlsSignature.AggregateVerify"/>
+        /// <seealso cref="BlsSignature.FastAggregateVerify"/>
+        /// <seealso cref="BlsSignature.MultiVerify"/>
         public byte[] Sign(byte[] message)
         {
             HashDigest<SHA256> hashed = HashDigest<SHA256>.DeriveFrom(message);
             return CryptoConfig.ConsensusCryptoBackend.Sign(hashed, this);
         }
 
+        /// <inheritdoc cref="Sign(byte[])"/>
         public byte[] Sign(ImmutableArray<byte> message) => Sign(message.ToArray());
 
+        /// <summary>
+        /// Encodes the private key into a corresponding mutable <see cref="byte"/> array
+        /// representation.
+        /// </summary>
+        /// <returns>An encoded <see cref="byte"/> array representation.  It guarantees that
+        /// returned arrays are never reused, and mutating on them does not affect
+        /// <see cref="BlsPrivateKey"/> instance's internal states.</returns>
+        /// <remarks>
+        /// An encoded <see cref="byte"/> array representation can be recovered to a <see
+        /// cref="BlsPrivateKey"/> instance again using
+        /// <see cref="BlsPrivateKey(IReadOnlyList{byte})"/> constructor.
+        /// <para>As like <see cref="BlsPrivateKey"/> instances, it also must be kept secret.
+        /// In practice, this must not be sent over the network, and be securely stored in the file
+        /// system.
+        /// </para>
+        /// <para>To get an immutable array instead of mutable one, use <see cref="ByteArray"/>
+        /// property.</para>
+        /// </remarks>
+        /// <seealso cref="ByteArray"/>
+        /// <seealso cref="BlsPrivateKey(IReadOnlyList{byte})"/>
         [Pure]
         public byte[] ToByteArray() => _privateKey.ToArray();
 

Libplanet/Crypto/BlsPublicKey.cs

@@ -9,12 +9,44 @@
 
 namespace Libplanet.Crypto
 {
-    public class BlsPublicKey : IEquatable<BlsPublicKey>, IECPublicKey
+    /// <summary>
+    /// A public key pair of
+    /// <a href="https://datatracker.ietf.org/doc/draft-irtf-cfrg-bls-signature/">BLS Signature</a>
+    /// used in consensus for verifying signature.
+    /// It can verify <see cref="BlsSignature"/>, which can be verified corresponding
+    /// <see cref="Libplanet.Crypto.BlsPublicKey"/> with message. Also <see cref="BlsSignature"/>
+    /// can be aggregated with another signatures, and can be verified with multiple corresponding
+    /// <see cref="Libplanet.Crypto.BlsPublicKey"/> by <see cref="BlsSignature.AggregateVerify"/>,
+    /// <see cref="BlsSignature.FastAggregateVerify"/> or <see cref="BlsSignature.MultiVerify"/>
+    /// for its use-case. The implementation uses the BLS12_381 curve type with minimal public key
+    /// size setting, which is the same configuration with Ethereum 2.0 Phase 0.
+    /// </summary>
+    /// <remarks>
+    /// The <see cref="BlsPublicKey"/> can be published publicly, and this is required to verify the
+    /// signature from a <see cref="BlsPrivateKey"/>. The received public key from any peer should
+    /// be checked with <see cref="ProofOfPossession"/> due to the availability of public key
+    /// aggregation. See
+    /// <a href="https://datatracker.ietf.org/doc/id/draft-halla
+    /// mbaker-threshold-sigs-02.html#name-rogue-key-attack">
+    /// Rouge Key Attack</a>.
+    /// <para>Every <see cref="BlsPublicKey"/> object is immutable.</para>
+    /// </remarks>
+    /// <seealso cref="Libplanet.Crypto.BlsPrivateKey"/>
+    public sealed class BlsPublicKey : IEquatable<BlsPublicKey>, IECPublicKey
     {
         private const int KeyByteSize = BLS.PUBLICKEY_SERIALIZE_SIZE;
 
         private readonly IReadOnlyList<byte> _publicKey;
 
+        /// <summary>
+        /// Creates a <see cref="BlsPublicKey"/> instance from the given
+        /// <see cref="byte"/> array (i.e., <paramref name="publicKey"/>).
+        /// </summary>
+        /// <param name="publicKey">A valid <see cref="byte"/> array that
+        /// encodes an BLS public key.</param>
+        /// <param name="proofOfPossession">A proof of possession of given public key. The policy
+        /// does not allow public key aggregation for safety. The every <see cref="BlsPublicKey"/>
+        /// should be non-aggregated public key, and has a pair <see cref="BlsPrivateKey"/>.</param>
         public BlsPublicKey(IReadOnlyList<byte> publicKey, BlsSignature proofOfPossession)
         {
             if (publicKey is ImmutableArray<byte> i ? i.IsDefaultOrEmpty : !publicKey.Any())
@@ -48,6 +80,18 @@ public BlsPublicKey(IReadOnlyList<byte> publicKey, BlsSignature proofOfPossessio
         public ECPublicKeyParameters KeyParam => throw new NotSupportedException(
             "Currently setting key with BLS key parameter is not supported.");
 
+        /// <summary>
+        /// Returns the corresponding Proof of Possession. Public key can be aggregated, therefore
+        /// some public key are not the true public key from a private key.
+        /// <para>The Proof of Possession
+        /// is used for validate whether the public key is derived from a private key.
+        /// </para>
+        /// </summary>
+        /// <returns>Returns the proof of possession of <see cref="BlsPublicKey"/>.</returns>
+        /// <remarks>The infinite public key (e.g., derived from zero private key) cannot be
+        /// validated with Proof of possession of its infinite signature and considered invalid.
+        /// Therefore, the infinite public key also can be filtered with proof of possession.
+        /// </remarks>
         [Pure]
         public BlsSignature ProofOfPossession { get; }
 
@@ -64,13 +108,45 @@ public bool Equals(BlsPublicKey? other) =>
 
         public override int GetHashCode() => ByteUtil.CalculateHashCode(ToByteArray());
 
+        /// <summary>
+        /// Encodes this public key into a mutable <see cref="byte"/> array representation.
+        /// </summary>
+        /// <returns>An encoded mutable <see cref="byte"/> array representation.  It can be
+        /// recovered to a <see cref="PublicKey"/> instance again using
+        /// <see cref="BlsPublicKey(IReadOnlyList{byte}, BlsSignature)"/> constructor.</returns>
+        /// <seealso cref="ToImmutableArray()"/>
+        /// <seealso cref="BlsPublicKey(IReadOnlyList{byte}, BlsSignature)"/>
         [Pure]
         public byte[] ToByteArray() => _publicKey.ToArray();
 
+        /// <summary>
+        /// Encodes this public key into a immutable <see cref="byte"/> array representation.
+        /// <para>To get an mutable one, use <see cref="ToByteArray()"/> method instead.</para>
+        /// </summary>
+        /// <returns>An encoded immutable <see cref="byte"/> array representation.  It can be
+        /// recovered to a <see cref="BlsPublicKey"/> instance again using
+        /// <see cref="BlsPublicKey(IReadOnlyList{byte}, BlsSignature)"/> constructor.</returns>
+        /// <seealso cref="BlsPublicKey(IReadOnlyList{byte}, BlsSignature)"/>
         [Pure]
         public ImmutableArray<byte> ToImmutableArray() =>
             ToByteArray().ToImmutableArray();
 
+        /// <summary>
+        /// Verifies whether a <paramref name="signature"/> proves authenticity of
+        /// <paramref name="message"/> with the corresponding <see cref="BlsPrivateKey"/>.
+        /// <para>If signature is aggregated, use <see cref="BlsSignature.AggregateVerify"/> or
+        /// <see cref="BlsSignature.FastAggregateVerify"/>.</para>
+        /// </summary>
+        /// <param name="message">A original plaintext message that the <paramref name="signature"/>
+        /// tries to prove its authenticity.  I.e., an argument data passed to
+        /// <see cref="BlsPrivateKey.Sign(byte[])"/> or <see
+        /// cref="BlsPrivateKey.Sign(ImmutableArray{byte})" /> methods.</param>
+        /// <param name="signature">A signature which tries to authenticity of
+        /// <paramref name="message"/>.  I.e., a data that <see cref="BlsPrivateKey.Sign(byte[])"/>
+        /// or <see cref="BlsPrivateKey.Sign(ImmutableArray{byte})"/> methods returned.</param>
+        /// <returns><c>true</c> if the <paramref name="signature"/> proves authenticity of
+        /// the <paramref name="message"/> with the corresponding <see cref="BlsPublicKey"/>.
+        /// Otherwise <c>false</c>.</returns>
         [Pure]
         public bool Verify(IReadOnlyList<byte> message, IReadOnlyList<byte> signature)
         {
@@ -99,6 +175,10 @@ public bool Verify(IReadOnlyList<byte> message, IReadOnlyList<byte> signature)
                 hashed, signature.ToArray(), this);
         }
 
+        /// <summary>
+        /// Gets the public key's hexadecimal representation in compressed form.
+        /// </summary>
+        /// <returns>The hexadecimal string of the public key bytes.</returns>
         public override string ToString() => ByteUtil.Hex(ToByteArray());
     }
 }