Documentation changes

Author: egregius313

java/ql/src/Security/CWE/CWE-522/InsecureLdapAuth.java

@@ -2,16 +2,40 @@
 <qhelp>
 
   <overview>
-    <p>When using the Java LDAP API to perform LDAPv3-style extended operations and controls, a context with connection properties including user credentials is started. Transmission of LDAP credentials in cleartext allows remote attackers to obtain sensitive information by sniffing the network.</p>
+    <p>
+      When using the Java LDAP API to perform LDAPv3-style extended operations
+      and controls, a context with connection properties including user
+      credentials is started. Transmission of LDAP credentials in cleartext
+      allows remote attackers to obtain sensitive information by sniffing the
+      network.
+    </p>
   </overview>
 
   <recommendation>
-    <p>Use LDAPS to send credentials through SSL or use SASL authentication.</p>
+    <p>
+      Use the <code>ldaps://</code> protocol to send credentials through SSL or
+      use SASL authentication.
+    </p>
   </recommendation>
 
   <example>
-    <p>The following example shows two ways of using LDAP authentication. In the 'BAD' case, the credentials are transmitted in cleartext. In the 'GOOD' case, the credentials are transmitted over SSL.</p>
-    <sample src="InsecureLdapAuth.java" />
+    <p>
+      In the following (bad) example, a <code>ldap://</code> URL is used and
+      credentials will be sent in plaintext.
+    </p>
+    <sample src="LdapAuthUseLdap.java"/>
+
+    <p>
+      In the following (good) example, a <code>ldaps://</code> URL is used so
+      credentials will be encrypted with SSL.
+    </p>
+    <sample src="LdapAuthUseLdaps.java"/>
+
+    <p>
+      In the following (good) example, a <code>ldap://</code> URL is used, but
+      SASL authentication is enabled.
+    </p>
+    <sample src="LdapEnableSasl.java"/>
   </example>
 
   <references>

java/ql/src/Security/CWE/CWE-522/InsecureLdapAuth.qhelp

@@ -0,0 +1,9 @@
+String ldapUrl = "ldap://ad.your-server.com:389";
+Hashtable<String, String> environment = new Hashtable<String, String>();
+environment.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
+environment.put(Context.PROVIDER_URL, ldapUrl);
+environment.put(Context.REFERRAL, "follow");
+environment.put(Context.SECURITY_AUTHENTICATION, "simple");
+environment.put(Context.SECURITY_PRINCIPAL, ldapUserName);
+environment.put(Context.SECURITY_CREDENTIALS, password);
+DirContext dirContext = new InitialDirContext(environment);

java/ql/src/Security/CWE/CWE-522/LdapAuthUseLdap.java

@@ -0,0 +1,9 @@
+String ldapUrl = "ldaps://ad.your-server.com:636";
+Hashtable<String, String> environment = new Hashtable<String, String>();
+environment.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
+environment.put(Context.PROVIDER_URL, ldapUrl);
+environment.put(Context.REFERRAL, "follow");
+environment.put(Context.SECURITY_AUTHENTICATION, "simple");
+environment.put(Context.SECURITY_PRINCIPAL, ldapUserName);
+environment.put(Context.SECURITY_CREDENTIALS, password);
+DirContext dirContext = new InitialDirContext(environment);

java/ql/src/Security/CWE/CWE-522/LdapAuthUseLdaps.java

@@ -0,0 +1,9 @@
+String ldapUrl = "ldap://ad.your-server.com:389";
+Hashtable<String, String> environment = new Hashtable<String, String>();
+environment.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
+environment.put(Context.PROVIDER_URL, ldapUrl);
+environment.put(Context.REFERRAL, "follow");
+environment.put(Context.SECURITY_AUTHENTICATION, "DIGEST-MD5 GSSAPI");
+environment.put(Context.SECURITY_PRINCIPAL, ldapUserName);
+environment.put(Context.SECURITY_CREDENTIALS, password);
+DirContext dirContext = new InitialDirContext(environment);