Add documentation for timeattack

mtglib/init.go

@@ -129,7 +129,15 @@ type EventStream interface {
 	Send(context.Context, Event)
 }
 
+// TimeAttackDetector is an abstraction that checks a time, taken from
+// the faketls client hello message. This timestamp is encoded into
+// client-generated random bytes and can be extracted after some client
+// hello verification.
+//
+// This is mostly to prevent replay attacks.
 type TimeAttackDetector interface {
+	// Valid returns an error if timestamp is invalid or should not be
+	// accepted.
 	Valid(time.Time) error
 }
 

timeattack/detector.go

@@ -29,6 +29,9 @@ func (d detector) Valid(then time.Time) error {
 	return nil
 }
 
+// NewDetector returns a new TimeAttackDetector which validates that
+// timestamp belongs to intervar [X-duration, X+duration], so a small
+// timeshift is acceptable.
 func NewDetector(duration time.Duration) mtglib.TimeAttackDetector {
 	return detector{
 		Duration: duration,

timeattack/init.go

@@ -1,7 +1,10 @@
+// TimeAttack has implementation of mtglib.TimeAttackDetector>
 package timeattack
 
 import "time"
 
-const (
-	DefaultDuration = 5 * time.Second
-)
+// DefaultDuration is a default duration when timestamps are acceptable.
+//
+// It means that all timestamps which are X-DefaultDuration <= X <=
+// X+DefaultDuration are fine.
+const DefaultDuration = 5 * time.Second

timeattack/noop.go

@@ -10,6 +10,7 @@ type noop struct{}
 
 func (n noop) Valid(_ time.Time) error { return nil }
 
+// NewNoop returns TimeAttackDetector which accepts all timestamps.
 func NewNoop() mtglib.TimeAttackDetector {
 	return noop{}
 }