Add documentation for antireplay package

antireplay/doc.go

@@ -0,0 +1,7 @@
+// Antireplay package has cache implementations that are effective
+// against replay attacks.
+//
+// To understand more about replay attacks, please read documentation
+// for mtglib.AntiReplayCache interface. This package has a list of some
+// implementations of this interface.
+package antireplay

antireplay/init.go

@@ -1,6 +1,11 @@
 package antireplay
 
 const (
-	DefaultMaxSize   = 1024 * 1024 // 1MiB
-	DefaultErrorRate = 0.001
+	// DefaultStableBloomFilterMaxSize is a recommended byte size for a
+	// stable bloom filter.
+	DefaultStableBloomFilterMaxSize = 1024 * 1024 // 1MiB
+
+	// DefaultStableBloomFilterErrorRate is a recommended default error
+	// rate for a stable bloom filter.
+	DefaultStableBloomFilterErrorRate = 0.001
 )

antireplay/noop.go

@@ -6,6 +6,9 @@ type noop struct{}
 
 func (n noop) SeenBefore(_ []byte) bool { return false }
 
+// NewNoop returns an implementation that does nothing. A corresponding
+// method always returns false, so this cache accepts everything you
+// pass to it.
 func NewNoop() mtglib.AntiReplayCache {
 	return noop{}
 }

antireplay/stable_bloom_filter.go

@@ -20,6 +20,18 @@ func (s *stableBloomFilter) SeenBefore(digest []byte) bool {
 	return s.filter.TestAndAdd(digest)
 }
 
+// NewStableBloomFilter returns an implementation of AntiReplayCache
+// based on stable bloom filter.
+//
+// http://webdocs.cs.ualberta.ca/~drafiei/papers/DupDet06Sigmod.pdf
+//
+// The basic idea of a stable bloom filter is quite simple: each time
+// when you set a new element, you randomly reset P elements. There is a
+// hardcore math which proves that if you choose this P correctly, you
+// can maintain the same error rate for a stream of elements.
+//
+// byteSize is the number of bytes you want to give to a bloom filter  .
+// errorRate is desired false-positive error rate                      .
 func NewStableBloomFilter(byteSize uint, errorRate float64) mtglib.AntiReplayCache {
 	sf := boom.NewDefaultStableBloomFilter(byteSize*8, errorRate) // nolint: gomnd
 	sf.SetHash(xxhash.New64())