diff --git a/CompactMPC/Buffers/BufferBuilder.cs b/CompactMPC/Buffers/BufferBuilder.cs index dcba491..14d288f 100644 --- a/CompactMPC/Buffers/BufferBuilder.cs +++ b/CompactMPC/Buffers/BufferBuilder.cs @@ -6,6 +6,9 @@ namespace CompactMPC.Buffers { + /// + /// Allows to build a byte buffer by composing existing buffers and integer values. + /// public class BufferBuilder { private MessageComposer _composer; diff --git a/CompactMPC/ObliviousTransfer/IGeneralizedObliviousTransfer.cs b/CompactMPC/ObliviousTransfer/IGeneralizedObliviousTransfer.cs index 6b8d69d..e07db2d 100644 --- a/CompactMPC/ObliviousTransfer/IGeneralizedObliviousTransfer.cs +++ b/CompactMPC/ObliviousTransfer/IGeneralizedObliviousTransfer.cs @@ -10,9 +10,33 @@ namespace CompactMPC.ObliviousTransfer { + /// + /// Common interface for 1-out-of-4 bit oblivious transfer implementations. + /// + /// "Generalized" currently refers to messages of arbitrary byte lengths as opposed to + /// the interface, which is specialized to single bit OT. + /// public interface IGeneralizedObliviousTransfer { + /// + /// Supplies the four options from the sender to the oblivious transfer. + /// + /// The network message channel to the receiver. + /// Array containing the four options supplied to 1-out-of-4 OT by the sender for each invocation. + /// The number of OT invocations in the transmission. + /// An asynchronous task which performs the server side of the oblivious transfer. + /// To increase efficiency, several invocations of OT can be batched into one transmission. Task SendAsync(IMessageChannel channel, Quadruple[] options, int numberOfInvocations, int numberOfMessageBytes); + + /// + /// Supplies the selection index from the client side to the oblivious transfer and returns the corresponding option from the server. + /// + /// The network message channel to the sender. + /// Array containing the selection index supplied to 1-out-of-4 OT by the client for each invocation. + /// The number of OT invocations in the transmission. + /// An asynchronous task performing the client side of the oblivious transfer and returning the array containing + /// the options as selected by the client retrieved from the server. + /// To increase efficiency, several invocations of OT can be batched into one transmission. Task ReceiveAsync(IMessageChannel channel, QuadrupleIndexArray selectionIndices, int numberOfInvocations, int numberOfMessageBytes); } } diff --git a/CompactMPC/ObliviousTransfer/IObliviousTransfer.cs b/CompactMPC/ObliviousTransfer/IObliviousTransfer.cs index dfe3eea..8eb65da 100644 --- a/CompactMPC/ObliviousTransfer/IObliviousTransfer.cs +++ b/CompactMPC/ObliviousTransfer/IObliviousTransfer.cs @@ -10,9 +10,32 @@ namespace CompactMPC.ObliviousTransfer { + /// + /// Common interface for 1-out-of-4 single bit oblivious transfer implementations. + /// + /// For a variant with arbitrary bit length for messages/options, see . + /// public interface IObliviousTransfer { + /// + /// Supplies the four options from the sender to the oblivious transfer. + /// + /// The network message channel to the receiver. + /// Array containing the four options supplied to 1-out-of-4 OT by the sender for each invocation. + /// The number of OT invocations in the transmission. + /// An asynchronous task which performs the server side of the oblivious transfer. + /// To increase efficiency, several invocations of OT can be batched into one transmission. Task SendAsync(IMessageChannel channel, BitQuadrupleArray options, int numberOfInvocations); + + /// + /// Supplies the selection index from the client side to the oblivious transfer and returns the corresponding option from the server. + /// + /// The network message channel to the sender. + /// Array containing the selection index supplied to 1-out-of-4 OT by the client for each invocation. + /// The number of OT invocations in the transmission. + /// An asynchronous task performing the client side of the oblivious transfer and returning the array containing + /// the options as selected by the client retrieved from the server. + /// To increase efficiency, several invocations of OT can be batched into one transmission. Task ReceiveAsync(IMessageChannel channel, QuadrupleIndexArray selectionIndices, int numberOfInvocations); } } diff --git a/CompactMPC/ObliviousTransfer/InsecureObliviousTransfer.cs b/CompactMPC/ObliviousTransfer/InsecureObliviousTransfer.cs index 1e6dad2..ffd48ca 100644 --- a/CompactMPC/ObliviousTransfer/InsecureObliviousTransfer.cs +++ b/CompactMPC/ObliviousTransfer/InsecureObliviousTransfer.cs @@ -9,6 +9,12 @@ namespace CompactMPC.ObliviousTransfer { + /// + /// Insecure (non-oblivious) implementation of the oblivious transfer interface. + /// + /// Caution! This class is intended for testing and debugging purposes and does not provide any security. + /// Hence, it should not be used with any sensitive or in production deployments. All options are SENT IN THE PLAIN. + /// public class InsecureObliviousTransfer : GeneralizedObliviousTransfer { protected override Task GeneralizedSendAsync(IMessageChannel channel, Quadruple[] options, int numberOfInvocations, int numberOfMessageBytes) diff --git a/CompactMPC/ObliviousTransfer/NaorPinkasObliviousTransfer.cs b/CompactMPC/ObliviousTransfer/NaorPinkasObliviousTransfer.cs index e2e5e25..8f57d6c 100644 --- a/CompactMPC/ObliviousTransfer/NaorPinkasObliviousTransfer.cs +++ b/CompactMPC/ObliviousTransfer/NaorPinkasObliviousTransfer.cs @@ -56,6 +56,9 @@ protected override async Task GeneralizedSendAsync(IMessageChannel channel, Quad listOfCs[i] = GenerateGroupElement(out exponent); listOfExponents[i] = exponent; }); + // note(lumip): we discussed a possible vulnerability arising when two or more group elements + // are similar but decided against checking for that since the probability of it occuring is + // negligible small for the relevant group sizes. BigInteger alpha = listOfExponents[0]; @@ -189,6 +192,11 @@ protected override async Task GeneralizedReceiveAsync(IMessageChannel return selectedOptions; } + /// + /// Returns a random element from the group as well as the corresponding exponent for the group generator. + /// + /// The exponent with which the returned group element can be obtained from the group generator. + /// A random group element. private BigInteger GenerateGroupElement(out BigInteger exponent) { // note(lumip): do not give in to the temptation of replacing the exponent > _parameters.Q part with a @@ -203,11 +211,22 @@ private BigInteger GenerateGroupElement(out BigInteger exponent) return BigInteger.ModPow(_parameters.G, exponent, _parameters.P); } + /// + /// Multiplicatively inverts a group element. + /// + /// The group element to be inverted. + /// The multiplicative inverse of the argument in the group. private BigInteger Invert(BigInteger groupElement) { return BigInteger.ModPow(groupElement, _parameters.Q - 1, _parameters.P); } + /// + /// Asynchronously writes a list of group elements (BigInteger) to a message channel. + /// + /// The network message channel. + /// The list of group elements to write/send. + /// private Task WriteGroupElements(IMessageChannel channel, IReadOnlyList groupElements) { MessageComposer message = new MessageComposer(2 * groupElements.Count); @@ -221,6 +240,12 @@ private Task WriteGroupElements(IMessageChannel channel, IReadOnlyList + /// Asynchronously reads a specified number of group elements from a message channel. + /// + /// The network message channel. + /// Number of group elements to read/receive. + /// private async Task ReadGroupElements(IMessageChannel channel, int numberOfGroupElements) { MessageDecomposer message = new MessageDecomposer(await channel.ReadMessageAsync()); diff --git a/CompactMPC/ObliviousTransfer/RandomOracle.cs b/CompactMPC/ObliviousTransfer/RandomOracle.cs index 0e7de44..51221c8 100644 --- a/CompactMPC/ObliviousTransfer/RandomOracle.cs +++ b/CompactMPC/ObliviousTransfer/RandomOracle.cs @@ -6,10 +6,41 @@ namespace CompactMPC.ObliviousTransfer { + /// + /// A random oracle as canonically defined. + /// + /// As per the canonical definition of the random oracle, it produces a random but deterministic output + /// for each unique query it is invoked on, i.e., the output is unpredictably random over different queries + /// but providing the same query will always yield the same output sequence. + /// + /// The RandomOracle class also provides a Mask message that masks a given message with the output of the + /// random oracle for a given query. In that case the query can be seen as a shared key that allows for + /// masking and unmasking (encryption/decryption) of a message. + /// + /// Naturally, a true random oracle cannot be implemented so the outputs of all implementations of + /// RandomOracle will not be perfectly random but computationally indistinguishable from true randomness + /// by the usual cryptographic standards. + /// public abstract class RandomOracle { + /// + /// Supplies the response of the random oracle to the given query. + /// + /// As per the canonical definition of the random oracle, it produces a random but deterministic output + /// for each unique query, i.e., the output is unpredictably random over different queries but + /// providing the same query will always yield the same output sequence. + /// + /// The query for the random oracle. + /// public abstract IEnumerable Invoke(byte[] query); + /// + /// Masks a given message by applying bitwise XOR with the random oracle output stream. + /// + /// The message to be masked with the random oracle output. + /// The query for the random oracle. + /// Byte array containing the masked message. + /// Thrown when the random oracle does not provide enough data to mask the given message. public byte[] Mask(byte[] message, byte[] query) { byte[] result = new byte[message.Length]; diff --git a/SampleCircuits/SecureSetIntersection.cs b/SampleCircuits/SecureSetIntersection.cs index 34908b8..3db46ef 100644 --- a/SampleCircuits/SecureSetIntersection.cs +++ b/SampleCircuits/SecureSetIntersection.cs @@ -9,6 +9,13 @@ namespace CompactMPC.SampleCircuits { + /// + /// Circuit which computes the intersection of sets given in a binary word representation. + /// + /// + /// In addition to the intersection result, a counter giving the cardinality of the intersection + /// is also calculated. + /// public class SecureSetIntersection { private SecureWord _intersection; @@ -25,6 +32,9 @@ public SecureSetIntersection(SecureWord[] inputs, int numberOfCounterBits) _counter = counter.OfFixedLength(numberOfCounterBits); } + /// + /// The binary encoding of the intersection set. + /// public SecureWord Intersection { get @@ -33,6 +43,9 @@ public SecureWord Intersection } } + /// + /// The number of elements in the intersection set. + /// public SecureInteger Counter { get