From bbd3ecb768678122b65ba33b970fbc42b950a66b Mon Sep 17 00:00:00 2001
From: Chris Smowton <smowton@github.com>
Date: Fri, 2 Jul 2021 09:26:08 +0100
Subject: [PATCH] Add docs to RandomQuery.qll

---
 .../semmle/code/java/security/RandomQuery.qll  | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/java/ql/src/semmle/code/java/security/RandomQuery.qll b/java/ql/src/semmle/code/java/security/RandomQuery.qll
index 2e844562260..4bc2f6364b1 100644
--- a/java/ql/src/semmle/code/java/security/RandomQuery.qll
+++ b/java/ql/src/semmle/code/java/security/RandomQuery.qll
@@ -1,3 +1,5 @@
+/** Provides clases and methods shared by randomness-related queries. */
+
 import java
 import semmle.code.java.dataflow.DefUse
 import semmle.code.java.dataflow.DataFlow6
@@ -89,6 +91,10 @@ private predicate safelySeeded(RValue use) {
   )
 }
 
+/**
+ * Holds if predictable seed `source` is used to initialise a random-number generator
+ * used at `use`.
+ */
 predicate unsafelySeeded(RValue use, PredictableSeedExpr source) {
   isSeedingSource(_, use, source) and
   not safelySeeded(use)
@@ -131,6 +137,10 @@ private predicate isSeedingConstruction(ClassInstanceExpr c, Expr arg) {
   c.getArgument(0) = arg
 }
 
+/**
+ * A constant, call to a `ReturnsPredictableExpr` method, or an array initialiser
+ * consisting entirely of the same.
+ */
 class PredictableSeedExpr extends Expr {
   PredictableSeedExpr() {
     this.(MethodAccess).getCallee() instanceof ReturnsPredictableExpr
@@ -145,9 +155,15 @@ class PredictableSeedExpr extends Expr {
   }
 }
 
+/**
+ * A method whose return value is predictable (not necessarily constant).
+ *
+ * Extend this class in order that all randomness-related queries should consider the result
+ * of a particular method predictable when noting bad RNG seeding and related issues.
+ */
 abstract class ReturnsPredictableExpr extends Method { }
 
-class ReturnsSystemTime extends ReturnsPredictableExpr {
+private class ReturnsSystemTime extends ReturnsPredictableExpr {
   ReturnsSystemTime() {
     this.getDeclaringType().hasQualifiedName("java.lang", "System") and
     this.hasName("currentTimeMillis")