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..5e948d3292625582c106f9f19847e76ab2d9332e
--- /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 that an application trusts will be publicly disclosed in a

[Eran Messeri, 2017/03/16 12:10:28]

very small nit: that ... that 
Can the 2nd 'that' simply be dropped?

[Ryan Sleevi, 2017/03/16 14:10:35]

Yup. Thanks

+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
+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
+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).
+
+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
+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
+other CAs provide. These policies are implemented in
+[`TransportSecurityState`](../http/transport_security_state.cc), via the
+`ShouldRequireCT` method
+
+### CTVerifier
+
+The `CTVerifier` is the core class for parsing and validating the structures
+defined in RFC6962 (or future versions), and providing basic information about
+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
+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`)
+  * 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
+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

[Eran Messeri, 2017/03/16 12:10:27]

Do I understand correctly that if said TransportSecurityState::RequireCTDelegate
implementation is overridden to not require CT for any certificate, then the
CTPolicyEnforcer isn't involved at all in the process?

[Ryan Sleevi, 2017/03/16 14:10:35]

Nope, because the CTPolicyEnforcer is still called beforehand, and if and only
if it fails (and not due to expiration) does it go to the RequireCTDelegate

+applications to inspect the connection information and determine whether
+CT should be required, CT should not be required, or whether the default logic
+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.
+
+The implementation of these policies lives within [`//net/cert`](../cert), and
+include:
+  * [`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)
+  * ['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
+    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
+
+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.