[Cronet] Public key pinning for Java API

components/cronet/android/api/src/org/chromium/net/CronetEngine.java

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 package org.chromium.net;
 
 import android.content.Context;
 import android.support.annotation.IntDef;
+import android.util.Base64;
 import android.util.Log;
 
 import org.json.JSONArray;
 import org.json.JSONException;
 import org.json.JSONObject;
 
 import java.io.File;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.reflect.Constructor;
 import java.net.Proxy;
 import java.net.URL;
 import java.net.URLConnection;
 import java.net.URLStreamHandlerFactory;
+import java.util.Collection;
+import java.util.Date;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.concurrent.Executor;
 
 /**
  * An engine to process {@link UrlRequest}s, which uses the best HTTP stack
  * available on the current platform.
  */
 public abstract class CronetEngine {
     /**
      * A builder for {@link CronetEngine}s, which allows runtime configuration of
      * {@code CronetEngine}. Configuration options are set on the builder and
@@ skipping 261 matching lines @@
                 hint.put(CronetEngineBuilderList.QUIC_HINT_PORT, port);
                 hint.put(CronetEngineBuilderList.QUIC_HINT_ALT_PORT, alternatePort);
                 quicHints.put(hint);
             } catch (JSONException e) {
                 // Intentionally do nothing.
             }
             return this;
         }
 
         /**
+         * Adds public key pins for a given host.
+         *
+         * @param hostName name of the host to which public keys should be pinned.
+         * @param pinsSha256 a collection of pins. Each pin is the SHA-256 cryptographic
+         *                   hash of DER-encoded ASN.1 representation of Subject Public
+         *                   Key Info (SPKI) of the host X.509 certificate. Use
+         *                   {@code security.cert.X509Certificate.getPublicKey().getEncoded()}
+         *                   to obtain DER-encoded ASN.1 representation of SPKI.
+         * @param includeSubdomains indicates whether the pinning policy should be applied to
+         *                          subdomains of {@code hostName}.
+         * @param expirationDate specifies the expiration date for the pins.
+         * @return the builder to facilitate chaining.
+         * @throws NullPointerException if one of the input parameters is null.
+         * @throws IllegalArgumentException if the given host name is invalid or {@code pinsSha256}
+         *                                  collection contains a byte array that does not represent
+         *                                  a valid SHA-256 hash.
+         */
+        public Builder addPublicKeyPins(String hostName, Collection<byte[]> pinsSha256,
+                boolean includeSubdomains, Date expirationDate) {

[estark, 2015/11/10 19:04:16]

This doesn't seem to match the API discussed in
https://docs.google.com/document/d/1HHN_dkfno9jIhglznyS6D86wlSaZf1zAcjZL_jsSl....
I thought we settled on addPublicKeyPins/removePublicKeyPins so that the caller
would manage the expiration? I think expiration date is kind of misleading
because the pins aren't persisted.

(https://docs.google.com/document/d/1HHN_dkfno9jIhglznyS6D86wlSaZf1zAcjZL_jsSl...
is the particular discussion I'm thinking of.)

[mef, 2015/11/10 22:19:03]

Good point. I forgot about that discussion. We've added expirationDate to match
design in this document:
https://docs.google.com/a/google.com/document/d/1hC_JDISiBoxqNHDxSgzsWD0id51v...
but I suppose it is not necessary.

[kapishnikov, 2015/11/10 22:33:33]

It is a good point. Currently addPublicKeyPins() is configuration time API used
to configure CronetEngine before its instantiation. Since the pins are not
persisted, removePublicKeyPins() has limited usability during the configuration.
It could only be used to cancel addPublicKeyPins() operation during the same
CronetEngine configuration session. It would make perfect sense to have
add/remove pair if we provided dynamic pinning or pin persistence.

Having expiration date is actually quite useful. My understanding is that in
most common use-case, the apps will contain hard-coded pins. Those pins will be
passed to CronetEngine on every app launch. If we don't provide expiration date,
the apps may stop working after the server certificate is expired and reissued
on the server. In order to prevent this situation, the pin can be set to expire
same time (or a little earlier) as the certificate.

[mef, 2015/11/18 22:41:38]

Emily, WDYT?

[estark, 2015/11/18 23:10:06]

Sorry for dropping off on this. I guess this seems okay to me, to match the
Android API.

+            if (hostName == null) {
+                throw new NullPointerException("The hostname cannot be null");
+            }
+            if (!isValidHostNameForPinning(hostName)) {
+                throw new IllegalArgumentException("Invalid host name: " + hostName);
+            }
+            if (pinsSha256 == null) {
+                throw new NullPointerException("The collection of SHA256 pins cannot be null");
+            }
+            try {
+                // Add HPKP_LIST JSON array element if it is not present.
+                JSONArray hpkpList = mConfig.optJSONArray(CronetEngineBuilderList.HPKP_LIST);
+                if (hpkpList == null) {
+                    hpkpList = new JSONArray();
+                    mConfig.put(CronetEngineBuilderList.HPKP_LIST, hpkpList);
+                }
+
+                // Convert the pin to BASE64 encoding.
+                Set<String> hashes = new HashSet<>(pinsSha256.size());
+                for (byte[] pinSha256 : pinsSha256) {
+                    hashes.add(convertSha256ToBase64WithPrefix(pinSha256));
+                }
+
+                // Add new element to HPKP_LIST JSON array.
+                JSONObject hpkp = new JSONObject();
+                hpkp.put(CronetEngineBuilderList.HPKP_HOST, hostName);
+                hpkp.put(CronetEngineBuilderList.HPKP_PIN_HASHES, new JSONArray(hashes));
+                hpkp.put(CronetEngineBuilderList.HPKP_INCLUDE_SUBDOMAINS, includeSubdomains);
+                // The expiration time is passed as a double, in seconds since January 1, 1970.
+                hpkp.put(CronetEngineBuilderList.HPKP_EXPIRATION_DATE,
+                        (double) expirationDate.getTime() / 1000);
+                hpkpList.put(hpkp);
+            } catch (JSONException e) {
+                // This exception should never happen.
+                throw new RuntimeException(
+                        "Failed to add pubic key pins with the given arguments", e);
+            }
+            return this;
+        }
+
+        /**
+         * Converts a given SHA256 array of bytes to BASE64 encoding with the prefix. The format
+         * corresponds to the format that is expected by net::HashValue class.
+         *
+         * @param sha256 SHA256 bytes to convert to BASE64.
+         * @return the BASE64 conversion.
+         * @throws IllegalArgumentException if the provided pin is invalid.
+         */
+        private static String convertSha256ToBase64WithPrefix(byte[] sha256) {
+            if (sha256 == null || sha256.length != 32) {
+                throw new IllegalArgumentException("Public key pin is invalid");
+            }
+            return "sha256/" + Base64.encodeToString(sha256, Base64.NO_WRAP);
+        }
+
+        /**
+         * Checks whether the given string that represents a host name is valid for HPKP.
+         * A valid host name should not match IPv4 address.

[estark, 2015/11/10 19:04:16]

ipv6 shouldn't be valid either

[mef, 2015/11/10 22:19:03]

I think ipv4 is checked explicitly as it includes dots, whereas ipv6 uses
semicolons, which are not allowed in host name anyway.

+         *
+         * @see <a href="https://tools.ietf.org/html/rfc7469#section-2.3.3>RFC 7469</a>
+         * @param hostName host name to check.
+         * @return true if the string is a valid host name.
+         */
+        private static boolean isValidHostNameForPinning(String hostName) {
+            return CronetUtil.isValidHostName(hostName) && !CronetUtil.isValidIPv4(hostName);
+        }
+
+        /**
          * Sets experimental QUIC connection options, overwriting any pre-existing
          * options. List of options is subject to change.
          *
          * @param quicConnectionOptions comma-separated QUIC options (for example
          * "PACE,IW10") to use if QUIC is enabled.
          * @return the builder to facilitate chaining.
          */
         public Builder setExperimentalQuicConnectionOptions(String quicConnectionOptions) {
             return putString(CronetEngineBuilderList.QUIC_OPTIONS, quicConnectionOptions);
         }
@@ skipping 372 matching lines @@
                 cronetEngine = possibleEngine;
             }
         } catch (ClassNotFoundException e) {
             // Leave as null.
         } catch (Exception e) {
             throw new IllegalStateException("Cannot instantiate: " + CRONET_URL_REQUEST_CONTEXT, e);
         }
         return cronetEngine;
     }
 }