DomainMatchRule and forDomains() support in MemorizingTrustManager

commonsguy · commonsguy · commit 98aa04a323b3 · 2017-02-13T10:52:16.000-05:00
diff --git a/docs/ADVANCED_USAGE.markdown b/docs/ADVANCED_USAGE.markdown
@@ -84,10 +84,15 @@ based on your supported API levels.
 These configuration methods are optional:
 
 - `noTOFU()` is to disable automatic trust-on-first-use behavior, described
-below
+below.
 
 - `cacheSize()` indicates how many domains' worth of memorized certificates
-should be held in cache (default: 128)
+should be held in cache (default: 128).
+
+- `forDomains()` indicates which domains should be memorized; all other
+domains will be ignored, as if this `TrustManager` were not involved. The
+default is to memorize all domains. This method takes a `DomainMatchRule`,
+described in detail later in this page.
 
 ### Adding the MemorizingTrustManager
 
@@ -210,6 +215,45 @@ instance that was outstanding at the time.
 The test suite for this library does use multiple `MemorizingTrustManager`
 instances, mostly to confirm that certificates do get loaded from disk.
 
+### Memorizing Certain Domains
+
+By default, `MemorizingTrustManager` applies for all domains that it sees.
+
+Alternatively, you can use `forDomains()` to limit the scope of the domains
+that `MemorizingTrustManager` worries about. `forDomains()` takes a
+`DomainMatchRule` as a parameter.
+
+The simplest ways to create a `DomainMatchRule` are the `whitelist()`
+and `blacklist()` static methods on that class. They each take one or more
+`String` parameters representing domains. Those can either be simple domains
+(e.g., `foo.com`) or with a leading wildcard (e.g., `*.foo.com`). `whitelist()`
+will apply the `MemorizingTrustManager` for the specified domains and skip
+it for anything else. `blacklist()` will skip the `MemorizingTrustManager`
+for the specified domains and apply it for anything else.
+
+`DomainMatchRule` has other static methods for more granular control:
+
+- `is(String)` takes a domain name or wildcard domain name and matches it
+but nothing else
+
+- `is(Pattern)` takes a `Pattern` (i.e., regular expression) and matches
+it but nothing else
+
+- `not(DomainMatchRule)` takes some other rule (e.g., one returned by `is()`)
+and inverts it
+
+- `anyOf(DomainMatchRule...)` and `anyOf(List<DomainMatchRule>)` apply a logical
+OR, so a domain matching any of those rules is applied
+
+- `allOf(DomainMatchRule...)` and `allOf(List<DomainMatchRule>)` apply a logical
+AND, so only domains matching all of those rules are applied
+
+For example, `whitelist()` is implemented by wrapping each supplied domain
+in `is()` and using `anyOf()` for the collection, so we accept any of those
+domains but nothing else. `blacklist()` is implemented by wrapping each supplied
+domain in `not(is())` and using `allOf()` for the collection, so we only accept
+domains that are not any of the supplied ones.
+
 ## Integration with NetCipher
 
 [NetCipher](https://github.com/guardianproject/NetCipher) is a library to
diff --git a/netsecurity/build.gradle b/netsecurity/build.gradle
@@ -5,6 +5,7 @@ dependencies {
     compile 'com.android.support:support-annotations:25.1.1'
     provided 'com.squareup.okhttp3:okhttp:3.6.0'
     androidTestCompile 'com.squareup.okhttp3:okhttp:3.6.0'
+    testCompile 'junit:junit:4.12'
 }
 
 android {
diff --git a/netsecurity/src/androidTest/java/com/commonsware/cwac/netsecurity/test/OkHttp3MemorizationTests.java b/netsecurity/src/androidTest/java/com/commonsware/cwac/netsecurity/test/OkHttp3MemorizationTests.java
@@ -28,6 +28,7 @@
 import okhttp3.OkHttpClient;
 import okhttp3.Request;
 import okhttp3.Response;
+import static com.commonsware.cwac.netsecurity.DomainMatchRule.is;
 
 @RunWith(AndroidJUnit4.class)
 public class OkHttp3MemorizationTests {
@@ -189,6 +190,23 @@ public void testTOFU() throws Exception {
     }
   }
 
+  @Test
+  public void testDomainMatchRule() throws Exception {
+    MemorizingTrustManager memo=new MemorizingTrustManager.Builder()
+      .saveTo(memoDir, "sekrit".toCharArray())
+      .noTOFU()
+      .forDomains(is("this-so-does-not-exist.com"))
+      .build();
+
+    final TrustManagerBuilder tmb=new TrustManagerBuilder().add(memo);
+
+    OkHttp3Integrator.applyTo(tmb, builder);
+    OkHttpClient client=builder.build();
+
+    Response response=client.newCall(buildRequest()).execute();
+    Assert.assertEquals(getExpectedResponse(), response.body().string());
+  }
+
   @Test
   public void testOr() throws Exception {
     MemorizingTrustManager memo=new MemorizingTrustManager.Builder()
diff --git a/netsecurity/src/main/java/com/commonsware/cwac/netsecurity/DomainMatchRule.java b/netsecurity/src/main/java/com/commonsware/cwac/netsecurity/DomainMatchRule.java
@@ -0,0 +1,209 @@
+/***
+ Copyright (c) 2017 CommonsWare, LLC
+
+ Licensed under the Apache License, Version 2.0 (the "License"); you may
+ not use this file except in compliance with the License. You may obtain
+ a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ */
+
+package com.commonsware.cwac.netsecurity;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.regex.Pattern;
+
+/**
+ * Represents a rule for identifying matching domain names. This is used
+ * by MemorizingTrustManager to limit the scope of memorization to only
+ * domains matching a rule.
+ *
+ * The whitelist() and blacklist() static methods implement two common
+ * patterns (accept only domains in a list or deny a list of domains and
+ * accept everything else). The other static methods allow you to assemble
+ * other scenarios. These methods are designed to be used as static imports,
+ * akin to Hamcrest matchers.
+ */
+abstract public class DomainMatchRule {
+  abstract public boolean matches(String host);
+
+  /**
+   * Implements a logical AND: only domains matching all of the supplied
+   * rules are considered to be a match.
+   *
+   * @param rules Rules to apply and AND together
+   * @return Rule implementing the AND logic
+   */
+  public static DomainMatchRule allOf(DomainMatchRule... rules) {
+    return(new Composite(false, rules));
+  }
+
+  /**
+   * Implements a logical AND: only domains matching all of the supplied
+   * rules are considered to be a match.
+   *
+   * @param rules Rules to apply and AND together
+   * @return Rule implementing the AND logic
+   */
+  public static DomainMatchRule allOf(List<DomainMatchRule> rules) {
+    return(new Composite(false, rules));
+  }
+
+  /**
+   * Implements a logical OR: any domains matching at least one of the supplied
+   * rules are considered to be a match.
+   *
+   * @param rules Rules to apply and OR together
+   * @return Rule implementing the OR logic
+   */
+  public static DomainMatchRule anyOf(DomainMatchRule... rules) {
+    return(new Composite(true, rules));
+  }
+
+  /**
+   * Implements a logical OR: any domains matching at least one of the supplied
+   * rules are considered to be a match.
+   *
+   * @param rules Rules to apply and OR together
+   * @return Rule implementing the OR logic
+   */
+  public static DomainMatchRule anyOf(List<DomainMatchRule> rules) {
+    return(new Composite(true, rules));
+  }
+
+  /**
+   * Inverts a rule, by applying a logical NOT to whatever it returns
+   * from matches()
+   *
+   * @param rule Rules to invert
+   * @return Rule implementing the NOT logic
+   */
+  public static DomainMatchRule not(DomainMatchRule rule) {
+    return(new Not(rule));
+  }
+
+  /**
+   * A concrete matcher, comparing domain names against the supplied
+   * regular expression.
+   *
+   * @param pattern Pattern to compare against domain names
+   * @return Rule implementing the pattern-match rule
+   */
+  public static DomainMatchRule is(Pattern pattern) {
+    return(new Regex(pattern));
+  }
+
+  /**
+   * A concrete matcher, comparing domain names against a "glob"-style
+   * expression. So, "foo.com" as a glob will only match "foo.com" as a
+   * domain. But "*.foo.com" as a glob will match "www.foo.com", "bar.foo.com",
+   * "www.bar.foo.com", and so on.
+   *
+   * @param glob Glob to compare against domain names
+   * @return Rule implementing the glob-match rule
+   */
+  public static DomainMatchRule is(String glob) {
+    return(new Regex(glob));
+  }
+
+  /**
+   * Accept any of the supplied globs, and reject anything else (see is(String)
+   * for what "glob" means).
+   *
+   * @param globs Globs to compare against domain names
+   * @return Rule implementing the whitelist
+   */
+  public static DomainMatchRule whitelist(String... globs) {
+    List<DomainMatchRule> rules=new ArrayList<>();
+
+    for (String glob : globs) {
+      rules.add(is(glob));
+    }
+
+    return(anyOf(rules));
+  }
+
+  /**
+   * Reject all of the supplied globs, and accept anything else (see is(String)
+   * for what "glob" means).
+   *
+   * @param globs Globs to compare against domain names
+   * @return Rule implementing the blacklist
+   */
+  public static DomainMatchRule blacklist(String... globs) {
+    List<DomainMatchRule> rules=new ArrayList<>();
+
+    for (String glob : globs) {
+      rules.add(not(is(glob)));
+    }
+
+    return(allOf(rules));
+  }
+
+  private static class Composite extends DomainMatchRule {
+    private final List<DomainMatchRule> rules;
+    private final boolean isOr;
+
+    Composite(boolean isOr, DomainMatchRule... rules) {
+      this(isOr, Arrays.asList(rules));
+    }
+
+    Composite(boolean isOr, List<DomainMatchRule> rules) {
+      this.isOr=isOr;
+      this.rules=rules;
+    }
+
+    @Override
+    public boolean matches(String host) {
+      for (DomainMatchRule rule : rules) {
+        boolean match=rule.matches(host);
+
+        if (match && isOr) {
+          return(true);
+        }
+        else if (!match && !isOr) {
+          return(false);
+        }
+      }
+
+      return(!isOr);
+    }
+  }
+
+  private static class Not extends DomainMatchRule {
+    private final DomainMatchRule rule;
+
+    Not(DomainMatchRule rule) {
+      this.rule=rule;
+    }
+
+    @Override
+    public boolean matches(String host) {
+      return(!rule.matches(host));
+    }
+  }
+
+  private static class Regex extends DomainMatchRule {
+    private final Pattern pattern;
+
+    Regex(String glob) {
+      this(Pattern.compile(glob.replaceAll("\\.", "\\\\.")
+        .replaceAll("\\*", "\\.\\*")));
+    }
+
+    Regex(Pattern pattern) {
+      this.pattern=pattern;
+    }
+
+    @Override
+    public boolean matches(String host) {
+      return(pattern.matcher(host).matches());
+    }
+  }
+}
diff --git a/netsecurity/src/main/java/com/commonsware/cwac/netsecurity/MemorizingTrustManager.java b/netsecurity/src/main/java/com/commonsware/cwac/netsecurity/MemorizingTrustManager.java
@@ -58,15 +58,17 @@ public class MemorizingTrustManager implements X509Extensions {
   private final String storeType;
   private final boolean noTOFU;
   private final LruCache<String, MemorizingStore> stores;
+  private final DomainMatchRule domainMatchRule;
 
   private MemorizingTrustManager(File workingDir, char[] storePassword,
                                  String storeType, boolean noTOFU,
-                                 int cacheSize) {
+                                 int cacheSize, DomainMatchRule domainMatchRule) {
     this.workingDir=workingDir;
     this.storePassword=storePassword;
     this.storeType=storeType;
     this.noTOFU=noTOFU;
     this.stores=new LruCache<>(cacheSize);
+    this.domainMatchRule=domainMatchRule;
   }
 
   /*
@@ -105,16 +107,18 @@ public List<X509Certificate> checkServerTrusted(
     @NonNull X509Certificate[] chain, String authType, String host)
     throws CertificateException {
 
-    try {
-      getStoreForHost(host).checkServerTrusted(chain, authType);
-    }
-    catch (Exception e) {
-      if (e instanceof CertificateNotMemorizedException ||
-        e instanceof MemorizationMismatchException) {
-        throw (CertificateException)e;
+    if (domainMatchRule==null || domainMatchRule.matches(host)) {
+      try {
+        getStoreForHost(host).checkServerTrusted(chain, authType);
       }
-      else {
-        throw new CertificateException("Exception setting up memoization", e);
+      catch (Exception e) {
+        if (e instanceof CertificateNotMemorizedException ||
+          e instanceof MemorizationMismatchException) {
+          throw (CertificateException)e;
+        }
+        else {
+          throw new CertificateException("Exception setting up memoization", e);
+        }
       }
     }
 
@@ -243,6 +247,7 @@ public static class Builder {
     private String storeType;
     private boolean noTOFU=false;
     private int cacheSize=128;
+    private DomainMatchRule domainMatchRule;
 
     /**
      * Indicates where the keystores associated with memorize() should
@@ -315,6 +320,12 @@ public Builder cacheSize(int cacheSize) {
       return(this);
     }
 
+    public Builder forDomains(DomainMatchRule domainMatchRule) {
+      this.domainMatchRule=domainMatchRule;
+
+      return(this);
+    }
+
     /**
      * Validates your configuration and builds the MemorizingTrustManager.
      *
@@ -335,7 +346,7 @@ public MemorizingTrustManager build() {
       workingDir.mkdirs();
 
       return(new MemorizingTrustManager(workingDir, storePassword, storeType,
-        noTOFU, cacheSize));
+        noTOFU, cacheSize, domainMatchRule));
     }
   }
 
diff --git a/netsecurity/src/test/java/com/commonsware/cwac/netsecurity/test/DomainMatchRuleTests.java b/netsecurity/src/test/java/com/commonsware/cwac/netsecurity/test/DomainMatchRuleTests.java

Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,7 @@ dependencies {`
`5`	`5`	`compile 'com.android.support:support-annotations:25.1.1'`
`6`	`6`	`provided 'com.squareup.okhttp3:okhttp:3.6.0'`
`7`	`7`	`androidTestCompile 'com.squareup.okhttp3:okhttp:3.6.0'`
	`8`	`+ testCompile 'junit:junit:4.12'`
`8`	`9`	`}`
`9`	`10`
`10`	`11`	`android {`