From 944d3c53fa86a89efc9211b9e57076aba2aab44f Mon Sep 17 00:00:00 2001
From: Simone Basso <bassosimone@gmail.com>
Date: Fri, 4 Jun 2021 12:50:23 +0200
Subject: [PATCH] doc: improve and reference existing bug in the code (#356)

---
 internal/engine/probeservices/register.go |  2 ++
 internal/platform/platform.go             | 10 +++-------
 internal/randx/randx.go                   | 15 +++++++++++----
 3 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/internal/engine/probeservices/register.go b/internal/engine/probeservices/register.go
index 7b2c31e..288e777 100644
--- a/internal/engine/probeservices/register.go
+++ b/internal/engine/probeservices/register.go
@@ -25,6 +25,8 @@ func (c Client) MaybeRegister(ctx context.Context, metadata Metadata) error {
 		return nil // we're already good
 	}
 	c.RegisterCalls.Add(1)
+	// TODO(bassosimone): here we should use a CSRNG
+	// (https://github.com/ooni/probe/issues/1502)
 	pwd := randx.Letters(64)
 	req := &registerRequest{
 		Metadata: metadata,
diff --git a/internal/platform/platform.go b/internal/platform/platform.go
index 964e122..a4b28ee 100644
--- a/internal/platform/platform.go
+++ b/internal/platform/platform.go
@@ -1,5 +1,5 @@
-// Package platform returns the platform name. The name returned here
-// is compatible with the names returned by Measurement Kit.
+// Package platform allows you to obtain the platform name. We use this
+// information to annotate measurements.
 package platform
 
 import "runtime"
@@ -18,11 +18,7 @@ import "runtime"
 //
 // 5. "unknown"
 //
-// The android, ios, linux, macos, windows, and unknown strings are
-// also returned by Measurement Kit. As a known bug, the detection of
-// darwin-based systems relies on the architecture, when CGO support
-// has been disabled. In such case, the code will return "ios" when
-// using arm{,64} and "macos" when using x86{,_64}.
+// You should use this name to annotate measurements.
 func Name() string {
 	return name(runtime.GOOS)
 }
diff --git a/internal/randx/randx.go b/internal/randx/randx.go
index 01af8ac..7fe705f 100644
--- a/internal/randx/randx.go
+++ b/internal/randx/randx.go
@@ -1,4 +1,6 @@
-// Package randx contains math/rand extensions.
+// Package randx contains math/rand extensions. The functions
+// exported by this package do not use a CSRNG so you SHOULD NOT
+// use these strings for, e.g., generating passwords.
 package randx
 
 import (
@@ -25,18 +27,23 @@ func lettersWithString(n int, letterBytes string) string {
 	return string(b)
 }
 
-// Letters return a string composed of random letters.
+// Letters return a string composed of random letters. Note that
+// this function uses a non-cryptographically-secure generator.
 func Letters(n int) string {
 	return lettersWithString(n, letters)
 }
 
-// LettersUppercase return a string composed of random uppercase letters.
+// LettersUppercase return a string composed of random uppercase
+// letters. Note that this function uses a non-cryptographically-secure
+// generator. So, we SHOULD NOT use it for generating passwords.
 func LettersUppercase(n int) string {
 	return lettersWithString(n, uppercase)
 }
 
 // ChangeCapitalization returns a new string where the capitalization
-// of each character is changed at random.
+// of each character is changed at random. Note that this function
+// uses a non-cryptographically-secure generator. So, we SHOULD NOT use
+// it for generating passwords.
 func ChangeCapitalization(source string) (dest string) {
 	rnd := rand.New(rand.NewSource(time.Now().UnixNano()))
 	for _, chr := range source {