Merge pull request #3837 from geoffw0/qldoc5

C++/Java: Update QLDoc and terminology in Encryption.qll

cpp/ql/src/Security/CWE/CWE-327/BrokenCryptoAlgorithm.ql

@@ -18,7 +18,7 @@ abstract class InsecureCryptoSpec extends Locatable {
 }
 
 Function getAnInsecureFunction() {
-  result.getName().regexpMatch(algorithmBlacklistRegex()) and
+  result.getName().regexpMatch(getInsecureAlgorithmRegex()) and
   exists(result.getACallToThisFunction())
 }
 
@@ -33,7 +33,7 @@ class InsecureFunctionCall extends InsecureCryptoSpec, FunctionCall {
 }
 
 Macro getAnInsecureMacro() {
-  result.getName().regexpMatch(algorithmBlacklistRegex()) and
+  result.getName().regexpMatch(getInsecureAlgorithmRegex()) and
   exists(result.getAnInvocation())
 }
 

cpp/ql/src/semmle/code/cpp/security/Encryption.qll

@@ -1,8 +1,13 @@
-// Common predicates relating to encryption in C and C++
+/**
+ * Provides predicates relating to encryption in C and C++.
+ */
+
 import cpp
 
-/** A blacklist of algorithms that are known to be insecure */
-string algorithmBlacklist() {
+/**
+ * Gets the name of an algorithm that is known to be insecure.
+ */
+string getAnInsecureAlgorithmName() {
   result = "DES" or
   result = "RC2" or
   result = "RC4" or
@@ -10,29 +15,36 @@ string algorithmBlacklist() {
   result = "ARCFOUR" // a variant of RC4
 }
 
-// these are only bad if they're being used for encryption, and it's
-// hard to know when that's happening
-string hashAlgorithmBlacklist() {
+/**
+ * Gets the name of a hash algorithm that is insecure if it is being used for
+ * encryption (but it is hard to know when that is happening).
+ */
+string getAnInsecureHashAlgorithmName() {
   result = "SHA1" or
   result = "MD5"
 }
 
-/** A regex for matching strings that look like they contain a blacklisted algorithm */
-string algorithmBlacklistRegex() {
+/**
+ * Gets the regular expression used for matching strings that look like they
+ * contain an algorithm that is known to be insecure.
+ */
+string getInsecureAlgorithmRegex() {
   result =
     // algorithms usually appear in names surrounded by characters that are not
     // alphabetical characters in the same case. This handles the upper and lower
     // case cases
-    "(^|.*[^A-Z])(" + strictconcat(algorithmBlacklist(), "|") + ")([^A-Z].*|$)" + "|" +
+    "(^|.*[^A-Z])(" + strictconcat(getAnInsecureAlgorithmName(), "|") + ")([^A-Z].*|$)" + "|" +
       // for lowercase, we want to be careful to avoid being confused by camelCase
       // hence we require two preceding uppercase letters to be sure of a case switch,
       // or a preceding non-alphabetic character
-      "(^|.*[A-Z]{2}|.*[^a-zA-Z])(" + strictconcat(algorithmBlacklist().toLowerCase(), "|") +
+      "(^|.*[A-Z]{2}|.*[^a-zA-Z])(" + strictconcat(getAnInsecureAlgorithmName().toLowerCase(), "|") +
       ")([^a-z].*|$)"
 }
 
-/** A whitelist of algorithms that are known to be secure */
-string algorithmWhitelist() {
+/**
+ * Gets the name of an algorithm that is known to be secure.
+ */
+string getASecureAlgorithmName() {
   result = "RSA" or
   result = "SHA256" or
   result = "CCM" or
@@ -42,17 +54,46 @@ string algorithmWhitelist() {
   result = "ECIES"
 }
 
-/** A regex for matching strings that look like they contain a whitelisted algorithm */
-string algorithmWhitelistRegex() {
-  // The implementation of this is a duplicate of algorithmBlacklistRegex, as it isn't
-  // possible to have string -> string functions at the moment
+/**
+ * Gets a regular expression for matching strings that look like they
+ * contain an algorithm that is known to be secure.
+ */
+string getSecureAlgorithmRegex() {
   // algorithms usually appear in names surrounded by characters that are not
   // alphabetical characters in the same case. This handles the upper and lower
   // case cases
-  result = "(^|.*[^A-Z])" + algorithmWhitelist() + "([^A-Z].*|$)"
+  result = "(^|.*[^A-Z])" + getASecureAlgorithmName() + "([^A-Z].*|$)"
   or
   // for lowercase, we want to be careful to avoid being confused by camelCase
-  // hence we require two preceding uppercase letters to be sure of a case switch,
-  // or a preceding non-alphabetic character
-  result = "(^|.*[A-Z]{2}|.*[^a-zA-Z])" + algorithmWhitelist().toLowerCase() + "([^a-z].*|$)"
+  // hence we require two preceding uppercase letters to be sure of a case
+  // switch, or a preceding non-alphabetic character
+  result = "(^|.*[A-Z]{2}|.*[^a-zA-Z])" + getASecureAlgorithmName().toLowerCase() + "([^a-z].*|$)"
 }
+
+/**
+ * DEPRECATED: Terminology has been updated. Use `getAnInsecureAlgorithmName()`
+ * instead.
+ */
+deprecated string algorithmBlacklist() { result = getAnInsecureAlgorithmName() }
+
+/**
+ * DEPRECATED: Terminology has been updated. Use
+ * `getAnInsecureHashAlgorithmName()` instead.
+ */
+deprecated string hashAlgorithmBlacklist() { result = getAnInsecureHashAlgorithmName() }
+
+/**
+ * DEPRECATED: Terminology has been updated. Use `getInsecureAlgorithmRegex()` instead.
+ */
+deprecated string algorithmBlacklistRegex() { result = getInsecureAlgorithmRegex() }
+
+/**
+ * DEPRECATED: Terminology has been updated. Use `getASecureAlgorithmName()`
+ * instead.
+ */
+deprecated string algorithmWhitelist() { result = getASecureAlgorithmName() }
+
+/**
+ * DEPRECATED: Terminology has been updated. Use `getSecureAlgorithmRegex()` instead.
+ */
+deprecated string algorithmWhitelistRegex() { result = getSecureAlgorithmRegex() }