Add documentation for Certificate Transparency in //net

net/docs/certificate-transparency.md

Index: net/docs/certificate-transparency.md
diff --git a/net/docs/certificate-transparency.md b/net/docs/certificate-transparency.md
new file mode 100644
index 0000000000000000000000000000000000000000..5599c7dcbe643960878de666cbdc2e05cd2cc9ba
--- /dev/null
+++ b/net/docs/certificate-transparency.md
@@ -0,0 +1,186 @@
+# Certificate Transparency
+
+## Overview
+
+[Certificate Transparency](http://www.certificate-transparency.org/) (CT) is a
+protocol designed to fix several structural flaws in the SSL/TLS certificate
+ecosystem. Described by [RFC 6962](https://tools.ietf.org/html/rfc6962) and
+the ongoing work in [RFC 6962-bis](https://datatracker.ietf.org/doc/draft-ietf-trans-rfc6962-bis/),
+it provides a means of providing a public, append-only data structure that
+can log certificates issued by [certificate authorities](https://en.wikipedia.org/wiki/Certificate_authority) (CAs).
+By logging these certificates, it becomes possible for site operators to
+detect when a certificate may have been issued for their domain without their
+approval, and allows browsers and the wider ecosystem to verify that CAs
+are following their expected and disclosed practices.
+
+## Certificate Transparency Basics
+
+Broadly speaking, the goal of supporting Certificate Transparency is to ensure
+that certificates an application trusts will be publicly disclosed in a way
+sufficient for site operators and application developers to ensure that
+nothing is wrong.
+
+At its most basic level, it's possible to simply introduce Certificate
+Transparency logs as trusted third parties, much like CAs are trusted third

[xunjieli, 2017/03/16 19:24:18]

nit: consider revising. I am not sure what "its" refers to in "At its most basic
level"

+parties. If the logs are operated by CAs, this may not be much of a security
+improvement, but if the logs are operated by non-CA entities, this might serve
+as a sufficient counter-balance to the risks.
+
+However, with more work, it's possible to minimize the trust afforded to CT

[xunjieli, 2017/03/16 19:24:18]

extra nitpicky: sometimes you refer to "Certificate Transparency log" and other
times the short version, "CT logs". Maybe consider standardize the usage?

+logs, and to automatically and cryptographically verify they're complying with
+their stated policies. This can provide even greater assurance to application
+developers, site operators, and their users, that the security expected from
+certificates is actually being provided.
+
+For a more thorough threat analysis, see 
+https://datatracker.ietf.org/doc/draft-ietf-trans-threat-analysis/ that
+discusses the different risks in Certificate Transparency, and how the
+protocol addresses them.
+
+## Certificate Transparency in `//net`
+
+A goal of `//net` is to try to ensure that code is 'safe by default' when
+used. As part of serving that goal, in order to make a TLS or QUIC connection
+using code in `//net`, it's necessary for the `//net` embedder to make
+a decision about Certificate Transparency, much like it is necessary to
+provide a [`CertVerifier`](../cert/cert_verifier.h) that describes how to
+verify the server's certificate.
+
+Because this is necessary to make a TLS or QUIC connection, this requirement
+surfaces upwards through each layer in the stack - applying to things like the
+[`HttpNetworkSession`](../http/http_network_session.h) and upwards to the
+[`URLRequestContext`](../url_request/url_request_context.h).

[xunjieli, 2017/03/16 19:24:18]

optional nit: maybe lose the articles in front of HttpNetworkSession and
URLRequestContext. I think them as proper nouns, but if you think otherwise,
please keep these articles.

+
+This requirement is expressed by requiring two separate, but related, objects
+to be supplied: A [`CTVerifier`](../cert/ct_verifier.h) and a
+[`CTPolicyEnforcer`](../cert/ct_policy_enforcer.h), which together can be used
+to express an application's policies with respect to Certificate Transparency.
+
+As part of the goal of ensuring 'safe by default', `//net` also has various
+policies related to certificates issues by particular certificate authorities

[xunjieli, 2017/03/16 19:24:18]

nit: s/issues/issued

+whose past actions have created unnecessary security risk for TLS connections,
+and as a consequence, are required to have their certificates disclosed using
+Certificate Transparency in order to ensure that the security provided by
+certificates from these CAs matches the level of security and assurance that

[xunjieli, 2017/03/16 19:24:18]

nitpicky to make this sentence flow a bit better:

s/"certificates from these CAs"/"these CAs"

because the comparison is done with "the level of security ... that other CAs
provide" and not "the level of security ... that provided by certificates from
other CAs"

+other CAs provide. These policies are implemented in
+[`TransportSecurityState`](../http/transport_security_state.cc), via the
+`ShouldRequireCT` method

[xunjieli, 2017/03/16 19:24:18]

nit: add a period at the end of the sentence.

+
+### CTVerifier
+
+The `CTVerifier` is the core class for parsing and validating the structures

[xunjieli, 2017/03/16 19:24:18]

optional nit:
Could consider removing "the" that's in front of CTVerifier and CTPolicyEnforcer
since they are proper nouns.

The `CTVerifier` is the core class -> `CTVerifier` is the core clas.

+defined in RFC6962 (or future versions), and providing basic information about

[xunjieli, 2017/03/16 19:24:18]

nit: s/"providing"/"for providing"

+the [`SignedCertificateTimestamps`](https://tools.ietf.org/html/rfc6962#section-3.2)
+present within the connection.
+
+### CTPolicyEnforcer
+
+The `CTPolicyEnforcer` is the core class for expressing an application's
+policies around how it expects Certificate Transparency to be used by the
+certificates it trusts and the certificate authorities that issue these

[xunjieli, 2017/03/16 19:24:19]

extra nitpicky: maybe shorten "certificate authorities" to CAs as you've done
elsewhere. It will probably make this sentence easier to scan.

+certificates.
+
+The `CTPolicyEnforcer` currently expresses two policies:
+  * How to treat [Extended Validation](https://cabforum.org/extended-validation-2/)
+    certificates (those for which a [`CertVerifier`](../cert/cert_verifier.h)
+    returned `CERT_STATUS_IS_EV`)

[xunjieli, 2017/03/16 19:24:19]

nit: add a period at the end of this sentence.

+  * How to treat all certificates, regardless of EV status.
+
+### TransportSecurityState
+
+The `TransportSecurityState::ShouldRequireCT` method implements the core logic
+for determining whether or not a connection attempt should be rejected if it
+does not comply with an application's Certificate Transparency policy.
+
+The implementation in `//net` provides a default implementation that tries to
+ensure maximum security, by causing connections that fail to abide by an

[xunjieli, 2017/03/16 19:24:19]

nit: consider revising the last part of the sentence.

by causing connections ... [to fail]?

or

by [failing] connections that don't abide by ...

+application's CT policy that are from CAs known to have security issues in the
+past.
+
+Embedders can customize or override this by providing a
+`TransportSecurityState::RequireCTDelegate` implementation, which allows
+applications to inspect the connection information and determine whether
+CT should be required, CT should not be required, or whether the default logic

[xunjieli, 2017/03/16 19:24:18]

nit: consider losing "CT should not be required," because the first whether
clause covers this scenario.

+in `//net` should be used.
+
+## Certificate Transparency in Chromium
+
+As part of the open-source implementation of Chrome, the policies related to
+how Chromium code treats Certificate Transparency are documented at
+https://www.chromium.org/Home/chromium-security/certificate-transparency . This
+page includes the policies for how Chromium determines an acceptable set of
+CT logs and what CT-related information is expected to accompany certificates,
+both for EV and non-EV.

[xunjieli, 2017/03/16 19:24:18]

extra nitpicky: maybe add a "certificates" at the end of the sentence.

+
+The implementation of these policies lives within [`//net/cert`](../cert), and
+include:

[xunjieli, 2017/03/16 19:24:19]

nit: s/include/includes

+  * [`ct_known_logs.h`](../cert/ct_known_logs.h): The set of CT logs known and
+    qualified according to Chromium's
+    [Certificate Transparency Log Policy](https://www.chromium.org/Home/chromium-security/certificate-transparency/log-policy)

[xunjieli, 2017/03/16 19:24:18]

nit: add a period at the end of this sentence.

+  * ['multi_log_ct_verifier.h`](../cert/multi_log_ct_verifier.h): Capable of
+    parsing SCTs from a variety of logs and validating their signatures, using

[xunjieli, 2017/03/16 19:24:18]

Excuse my ignorance. It will be helpful to spell out "SCT" here as you did
before using CT as a short-hand.

+    the keys and information provided by `ct_known_logs.h`.
+  * [`ct_policy_enforcer.h`](../cert/ct_policy_enforcer.h): A base class that
+    implements the Certificate Transparency in Chrome Policy, for both EV and
+    non-EV certificates.
+
+## Certificate Transparency for `//net` Consumers
+
+Not every TLS connection may need the security assurances that
+Certificate Transparency aims to provide. For example, some consumers of
+`//net` APIs in Chromium use mutual authentication with self-signed
+certificates and which are authenticated out-of-band. For these connections,
+Certificate Transparency is not relevant, and it's not necessary to parse
+or enforce CT related information.
+
+For these cases, the approach is:
+  * [`do_nothing_ct_verifier.h`](../cert/do_nothing_ct_verifier.h): A no-op
+    CTVerifier that does not parse or verify CT-related information.
+  * A derived `CTPolicyEnforcer` implementation that indicates all
+    certificates comply with its policies.
+    **TODO(rsleevi):** Provide a DoNothingCTPolicyEnforcer
+
+As documented in these classes, care should be taken before using these, as
+they provide much weaker security guarantees. In general, emailing
+net-dev@chromium.org or discussing it during a security review is the right
+answer, and documenting at the instantiation points why it is safe and
+acceptable to use these classes.
+
+## Certificate Transparency for `//net` Embedders

[xunjieli, 2017/03/16 19:24:18]

Could you include a sentence or two to explain the main differences between a
"net// Consumer" and a "net// Embedder" ?
I can make a guess but it'll be helpful to have the definition spelt out in this
section or the previous one.

+
+For projects and third party products that embed `//net`, the policies
+that are included as part of the open-source repository may not be
+appropriate. This is because the implementations may rely implicitly
+or explicitly on several key guarantees that come from Google-branded
+distributions and products, and may not be appropriate for other cases.
+
+These key expectations are:
+  * A release cycle aligned with Chrome releases; that is, every six weeks,
+    and on the same versions as Chrome releases.
+  * Widespread support for automatic updates.
+  * That [`base::GetBuildTime()`](../../base/build_time.h) will reflect, to
+    some degree, when the tree was branched and/or released, and will not
+    be re-generated on recompilation. That is, this implies is_official_build
+    for binaries released to end-users, but is not enforced in code so that
+    developers can accurately test release behavior.
+  * Support for dynamic [`base::FieldTrial`](../../base/metrics/field_trial.h)
+    configurations.
+
+For projects that don't support automatic updates, or which measure 'stable'
+on the order of months to years, or which don't have tools suitable to
+respond to changes in the Certificate Authority and Certificate Transparency
+ecosystem, it may not be appropriate to enable Certificate Transparency
+support yet.
+
+These issues are not unique or particular to Certificate Transparency - in
+many ways, they're similar to issues already faced with determining which
+certificate authorities are trusted and how to successfully validate a
+TLS server's certificate. However, as the Certificate Transparency ecosystem
+is still growing, it may be suitable to disable support until some of the
+solutions to these challenges stablize.
+
+To opt-out of enforcing Certificate Transparency, using the `DoNothing`
+variants discussed above provides a suitable implementation that will opt to
+'fail open' instead. This may provide less security, but provides greater
+stability, and minimizes the risk that these `//net` embedding clients
+might cause to the CT ecosystem or receive from enabling CT.