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..496828db03934534729fa4c444480d4ec3b1c212
--- /dev/null
+++ b/net/docs/certificate-transparency.md
@@ -0,0 +1,201 @@
+# 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 the 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
+Certificate Transparency 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
+[`HttpNetworkSession`](../http/http_network_session.h) and upwards to
+[`URLRequestContext`](../url_request/url_request_context.h).
+
+This requirement is expressed by requiring two separate, but related, objects
+to be supplied: [`CTVerifier`](../cert/ct_verifier.h) and
+[`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 issued by particular CAs 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
+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
+
+`CTVerifier` is the core interface for parsing and validating the structures
+defined in RFC6962 (or future versions), and for providing basic information
+about the [`SignedCertificateTimestamps`](https://tools.ietf.org/html/rfc6962#section-3.2)
+present within the connection.
+
+### CTPolicyEnforcer
+
+`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 CAs that issue these certificates.
+
+`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 failing connections that do not abide by an
+application's Certificate Transparency policy and 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
+Certificate Transparency should be required, 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
+Certificate Transparency logs and what Certificate Transparency-related
+information is expected to accompany certificates, both for EV and non-EV.
+
+The implementation of these policies lives within [`//net/cert`](../cert), and
+includes:
+  * [`ct_known_logs.h`](../cert/ct_known_logs.h): The set of Certificate
+    Transparency 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 `SignedCertificateTimestamps` s 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
+
+This section is intended for code that is open-sourced as part of the
+Chromium projects, intended to be included within Google Chrome, and which
+uses the `//net` APIs for purposes other than loading and rendering web
+content. Particularly, consumers of `//net` APIs that are communicating with
+a limited or defined set of endpoints and which don't use certificates issued
+by CAs. This may also include testing tools and utilities, as these are not
+generally shipped to users as part of Chrome.
+
+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 Certificate Transparency 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 Certificate Transparency-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
+
+This section is intended for code that is used in other open-source Chromium
+based projects, but are not included in Google Chrome or related. This
+includes projects based on `//net`, such as `//components/cronet` or other
+`//content` 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
+CAs 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 Certificate Transparency ecosystem or receive from enabling
+Certificate Transparency.