Added documentation for crypto queries

Author: fegge

cpp/src/docs/crypto/CustomAllocatorLeak.md

@@ -1 +1,23 @@
 # Custom allocator leak
+
+This query identifies potential memory leaks from custom allocators like
+`BN_new`. 
+
+The following example would be identified by the query as a potential memory
+leak.
+
+```cpp
+int compute(BIGNUM* a) {
+  BIGNUM *b = BN_new();
+
+  // Perform computation on `a` and `b`.
+
+  if (condition(a)) {
+    BN_free(b);
+    return a;
+  }
+
+  // The BIGNUM `b` may leak here.
+  return a;
+}
+```

cpp/src/docs/crypto/CustomAllocatorUseAfterFree.md

@@ -1 +1,23 @@
 # Custom allocator use-after-free
+
+This query identifies use-after-frees with custom allocators like `BN_new`.
+
+The following code snippet would be identified as an issue by the query.
+
+```cpp
+BIGNUM* compute(BIGNUM* a) {
+  BIGNUM *b = BN_new();
+
+  if (condition(a)) {
+    // The BIGNUM `b` may be freed here.
+    BN_free(b);
+  }
+  // Potential use-after-free of `b` here.
+  if (condition(b)) {
+    BN_free(a);
+    a = BN_new();
+  }
+
+  return b;
+}
+```

cpp/src/docs/crypto/ErrorHandling.md

@@ -1 +1,18 @@
-# RAND_bytes and BN_rand error handling
+# Checking if returned error codes are acted on
+
+Many of the functions comprising the OpenSSL API return an integer error code
+where 1 typically signals success, and 0 signals failure. To ensure that the
+implementation is secure, these error codes must be checked and acted upon. This
+query attempts to identify locations where a returned error code is not checked
+by the codebase. In this context, checked means that the return value flows
+to the condition of a control-flow statement like an if-statement, a while-
+statement, or a switch-statement.
+
+As an example, the following example function fails to check the return value
+from `RAND_bytes`, and would be flagged as an issue by the query.
+
+```cpp
+void generateEncryptionKey(unsigned char *key, size_t keySize) {
+    RAND_bytes(key, keySize);
+}
+```

cpp/src/docs/crypto/InvalidKeySize.md

@@ -1 +1,19 @@
 # Invalid key size
+
+The `EVP_EncryptInit` and `EVP_EncryptInit_ex` functions do not take the size
+of the key as input, and the implementation will simply read the expected number
+of bytes from the buffer. This query will check if the size of the key buffer
+passed as an argument to one of these functions is equal to the key size of the
+corresponding cipher.
+
+The following code snippet is aan example of an issue that would be identified
+by the query.
+
+```cpp
+unsigned char key[16];  // This should be 32 for a 256 bit key
+RAND_bytes(key, sizeof(key));
+
+unsigned char *iv = (unsigned char *)"0123456789ABCDEF";  // A fixed 16 byte IV
+
+EVP_EncryptInit_ex(EVP_CIPHER_CTX_new(), EVP_aes_256_cbc(), NULL, key, iv);
+```

cpp/src/docs/crypto/MissingEngineInit.md

@@ -1 +1,15 @@
 # Missing engine initialization
+
+This query identifies loaded OpenSSL engines which are not passed to both
+`ENGINE_init` and `ENGINE_set_default`. `ENGINE_init` should always be called
+when a new engine is loaded. It is generally good practise to also call
+`ENGINE_set_default` to ensure that the primitives defined by the engine are
+used by default.
+
+The following code snippet would be flagged as an issue by the query.
+
+```cpp
+ENGINE* load_rdrand() {
+    return ENGINE_by_id("rdrand");
+}
+```

cpp/src/docs/crypto/MissingZeroization.md

@@ -1 +1,21 @@
-# Non-cleared bignum detection
+# Missing zeroization of random BIGNUMs
+
+Randomly generated BIGNUMs often represent sensitive data (e.g. like ECDSA
+nonces). These should be cleared as they go out of scope to ensure that
+sensitive data does not remain in memory longer than required. 
+
+This query identifies OpenSSL BIGNUMs which are inititialized using `BN_rand`
+but not which are not zeroized using `BN_clear` before they go out of scope. The
+following example function would be flagged as an issue by the query.
+
+```cpp
+void compute() {
+    BIGNUM *n = BN_new();
+    BN_rand(n, 128, BN_RAND_TOP_ANY, BN_RAND_BOTTOM_ANY);
+    
+    // Perform sensitive computation using `n`.
+
+    BN_free(n);
+}
+```
+

cpp/src/docs/crypto/RandomBufferTooSmall.md

@@ -1 +1,17 @@
 # Random buffer too small
+
+This query finds buffer overflows in calls to CSPRNGs like `RAND_bytes`,
+`RAND_bytes_ex`, and `RAND_priv_bytes`. It is currently restricted to statically
+allocated buffers to allow us to easily determine the input buffer size, but
+could easily be extended to dynamically allocated buffers as well.
+
+The following example code would be flagged as vulnerable by the query.
+
+```cpp
+#define KEY_SIZE 16
+
+// ...
+
+unsigned char key[KEY_SIZE];
+int res = RAND_bytes(key, 32)
+```

cpp/src/docs/crypto/StaticKeyFlow.md

@@ -1 +1,5 @@
 # Static key flow
+
+This query flags locations where a static buffer is used as an argument to a
+function requiring strong, cryptographic level randomness (e.g. an encryption
+key).

cpp/src/docs/crypto/StaticPasswordFlow.md

@@ -1 +1,5 @@
 # Static password flow
+
+This query flags locations where a static string is used as an argument to a
+function requiring a strong password (e.g. the password argument for a password-
+based key derivation function).

cpp/src/docs/crypto/UseOfLegacyAlgorithm.md

@@ -1 +1,26 @@
 # Legacy cryptographic algorithm
+
+This query finds uses of weak or depracated cryptographic algorithms like `MD5`,
+`SHA1`, and `DES`. The query will flag calls to functions containing any of the
+following names:
+
+  - `MD2`
+  - `MD4`
+  - `MD5`
+  - `RIPEMD`
+  - `SHA1`
+  - `Streebog`
+  - `Whirlpool`
+
+  - `PBKDF1`
+
+  - `Arcfour`
+  - `Blowfish`
+  - `CAST`
+  - `DES`
+  - `IDEA`
+  - `Kasumi`
+  - `Magma`
+  - `RC2`
+  - `RC4`
+  - `TDEA`