1# Certificate Transparency 2 3[TOC] 4 5## Overview 6 7Certificate Transparency (CT) is a protocol designed to fix several structural 8flaws in the SSL/TLS certificate ecosystem. Described in 9[RFC 6962](https://tools.ietf.org/html/rfc6962), it provides a public, 10append-only data structure that can log certificates that are issued by 11[certificate authorities](https://en.wikipedia.org/wiki/Certificate_authority) (CAs). 12By logging certificates, it becomes possible for the public to see what 13certificates have been issued by a given CA. This allows site operators to 14detect when a certificate has been issued for their domains, allowing them to 15check for unauthorized issuance. It also allows browsers and root stores, and 16the broader community, to examine the certificates a CA has issued and ensure 17that the CA is complying with their expected or disclosed practices. 18 19For more information about how Certificate Transparency works, see: 20 * https://www.certificate-transparency.org 21 * [Introducing Certificate Transparency and Nimbus](https://blog.cloudflare.com/introducing-certificate-transparency-and-nimbus/) 22 23## Certificate Transparency for Site Operators 24 25### Basics 26 27We say that a certificate supports Certificate Transparency if it comes with 28CT information that demonstrates it has been logged in several CT logs. This 29CT information must comply with the 30[Certificate Transparency in Chrome](https://github.com/chromium/ct-policy/blob/master/ct_policy.md) 31policy. We sometimes refer to a site that "supports" CT as using a certificate 32that is "CT qualified" or "disclosed via CT." 33 34In general, a site operator does not need to take special action to 35support Certificate Transparency. This is because RFC 6962 defines three ways 36of providing the necessary information for CT: within the certificate, within 37a stapled OCSP response, or directly by the TLS server. Nearly every CA 38supports CT through the first method, meaning that when you get a certificate, 39it will already support CT and require no further configuration. If you are 40using a cloud provider to terminate your TLS connections, the cloud provider 41may also support CT via TLS, requiring no further action on your part. 42 43Supporting CT within the certificate itself is the preferred and recommended 44way to enable CT support. If you obtain a certificate from your CA and it does 45not support CT, then that generally indicates that your CA is not following 46industry best practice, and you should probably look for another CA to provide 47certificates for your sites. 48 49Configuring support for CT via the TLS extension is not recommended for most 50site operators. This is because supporting CT via this method requires 51constant monitoring of the CT ecosystem, such as for changes in the list of 52trusted logs or testing compatibility with various CT-supporting clients. This 53method works well for organizations with the ability to dedicate resources to 54that, such as hosting and cloud providers. If you are hosting your own website, 55you should try to ensure that your certificates support CT, and avoid supporting 56CT via the TLS extension. Supporting CT via the TLS extension may require rapid 57changes to your configuration, and thus may be riskier for organizations 58without staff dedicated to this. 59 60If you are getting longer-lived certificates (for example, 1 year), it's 61possible that changes in the CT ecosystem may mean that the CT information may 62expire before the certificate expires. If your CA also supports delivering CT 63via OCSP responses, then supporting OCSP stapling on your server may allow 64fresh CT information to be provided without having to replace the certificate. 65Alternatively, if your server does not support OCSP stapling, or your CA does 66not support CT in their OCSP responses, you may need to replace your certificate. 67 68These policies only apply to publicly-trusted CAs - that is, CAs that your 69browser or device trust without any additional configuration. For organizations 70using their own CAs, or for locally installed CAs, see 71[Certificate Transparency for Enterprises](#Certificate-Transparency-For-Enterprises). 72 73### Chrome Policies 74 75Chrome has gradually required Certificate Transparency for more and more 76publicly-trusted certificates over the past few years. 77 78* [Since 1 January 2015](https://github.com/chromium/ct-policy/blob/master/ct_policy.md), 79Chrome has required that all Extended Validation certificates be disclosed via 80Certificate Transparency. Certificates that were not properly disclosed would 81be [stripped of their EV status](https://news.netcraft.com/archives/2015/08/24/thousands-short-changed-by-ev-certificates-that-dont-display-correctly-in-chrome.html), 82but no warnings would be shown to visitors to sites that did not comply. 83 84* [Since 1 June 2016](https://security.googleblog.com/2015/10/sustaining-digital-certificate-security.html), 85Chrome has required that all new certificates issued by the set of root 86certificates owned by Symantec Corporation are disclosed via Certificate 87Transparency. Certificates that were not disclosed, or which were not disclosed 88in a way consistent with RFC 6962, would be rejected as untrusted. 89 90* For all new certificates issued after 30 April 2018, [Chrome will require that 91the certificate be disclosed via Certificate 92Transparency](https://groups.google.com/a/chromium.org/d/msg/ct-policy/wHILiYf31DE/iMFmpMEkAQAJ). 93If a certificate is issued after this date and neither the certificate nor 94the site supports CT, then these certificates will be rejected as untrusted, and 95the connection will be blocked. In the case of a main page load, the user will 96see a full page certificate warning page, with the error code 97`net::ERR_CERTIFICATE_TRANSPARENCY_REQUIRED`. If you receive this error, this 98indicates that your CA has not taken steps to make sure your certificate 99supports CT, and you should contact your CA's sales or support team to ensure 100you can get a replacement certificate that works. 101 102### Domain Privacy 103 104Supporting CT by disclosing the certificate to a CT Log means that the full 105contents of the certificate will be publicly accessible and viewable. In 106particular, this means that the domains a certificate are for will be included 107in the Certificate Transparency log, as well as the organization they are 108affiliated with, if they are validated to a level higher than Domain 109Validation or issued from an organization-specific CA. 110 111For most certificates, this is no different than what is already available. 112Publicly-trusted certificates have been subject to aggregation for public 113analysis for some time, such as through products and tools such as 114[Censys](https://censys.io/) or [scans.io](https://scans.io/). While 115Certificate Transparency provides an interoperable protocol for exchanging 116these datasets, in many cases, the certificate details and domains were already 117publicly detectable. 118 119Requiring that the full certificate be disclosed if it was issued by a 120publicly-trusted CA is an important part of the security goals of Certificate 121Transparency. Permitting some of the information to be hidden from 122certificates allows for both attackers and untrustworthy CAs to hide 123certificates that could be used to compromise users. Certificate Transparency 124has detected issues at a large 125[number of CAs](https://wiki.mozilla.org/CA/Incident_Dashboard), many that the 126CAs themselves were not even aware of, and so public disclosure is critical 127to keeping all users safe. 128 129While proposals for hiding domain names were presented during the development 130of Certificate Transparency, none of them were able to balance the needs of 131site operators that did not need to hide their domains, those that did, and the 132security risks that users would face. 133 134Because of this, Chrome does not support any method for hiding domain names or 135other information within publicly-trusted certificates, nor are there any plans 136to support such mechanisms. Domain operators that wish to hide their 137certificates, enabling security risks and attacks, have two options: 138 1391. **Wildcard Certificates** - Wildcard certificates allow a single certificate 140 to be used for multiple hostnames, by putting a `*` as the most specific 141 DNS label (for example, `*.internal.example.com` is valid for 142 `mail.internal.example.com` and `wiki.internal.example.com`, but not for 143 `www.example.com` or `two.levels.internal.example.com`). Wildcard 144 certificates require greater care by the site operator to protect their 145 private key, but also can have their issuance controlled via technologies 146 such as [CAA (RFC 6844)](https://tools.ietf.org/html/rfc6844). This still 147 requires the certificate be disclosed, but can limit how much of the domain 148 is disclosed. 1492. **Enterprise-specific configuration** - If the domains being accessed are 150 not intended to be used on the public internet, or not on machines or by 151 users that are not part of a single enterprise, then that enterprise can 152 use the options in the 153 [Certificate Transparency for Enterprises](#Certificate-Transparency-For-Enterprises). 154 This allows the enterprise to not reveal any information about the 155 certificate, but these certificates will **only** be trusted by their 156 members. 157 158### What to do if your certificate does not work 159 160As noted in [Chrome Policies](#Chrome-Policies), all certificates issued after 16130 April 2018 are expected to be disclosed via Certificate Transparency in a 162way that is compliant with the Certificate Transparency in Chrome policy. 163Virtually all publicly-trusted CAs have committed to supporting CT for their 164customers by default by this date, meaning that site operators should not have 165to do anything special and can continue getting certificates that just work on 1661 May 2018. 167 168However, there's still a chance that a CA may not have adopted Certificate 169Transparency, may have an infrastructure issue, or may not have communicated 170to their partners, such as resellers or subordinate CAs, to ensure that the 171transition would be as smooth as possible for their customers. 172 173If you're receiving a `net::ERR_CERTIFICATE_TRANSPARENCY_REQUIRED` error 174message, the best thing to do is to contact your CA's support or sales team 175to diagnose the error with them. They will most likely need to replace your 176certificate with a new one that properly supports CT. 177 178## Certificate Transparency for Enterprises 179 180### Locally-trusted CAs 181 182Certificate Transparency only applies to CAs that are publicly-trusted - that 183is, CAs that are supported by your browser or device out of the box, without 184any additional configuration steps. 185 186For CAs that have been manually installed, provided those certificates are not 187or have not been publicly-trusted, it's not necessary to enable support for 188Certificate Transparency. Further, Certificate Transparency Logs will not 189accept certificates from those CAs, thus it's not possible to support CT. 190 191In some cases, an Enterprise may have a locally-trusted CA that has been 192manually installed, but it was previously publicly-trusted. For example, this 193CA may have been removed by a browser or an OS for not complying with the 194root store policies, but the Enterprise may still have a dependency on 195trusting this CA. In these cases, the Enterprise can use 196[Enterprise Policies](#Enterprise-Policies) to configure how Certificate 197Transparency will be enforced for those CAs. 198 199### Private Domain Names 200 201For Enterprises that have domain names that are internal to their organization, 202and do not need to be publicly-trusted by default, several options exist to 203enable these domains to be kept private, while allowing the certificates to 204still be used, without error, for users in their organization. 205 206The recommended option is to no longer rely on publicly-trusted certificates 207to serve these domains, as they are organization specific. For example, such 208organizations can use a private CA, which [several](https://aws.amazon.com/certificate-manager/private-certificate-authority/) 209[CAs](https://www.digicert.com/private-pki/) [offer](https://www.comodo.com/business-security/pki-management/certificate-manager.php). 210Using a hosted, managed PKI may help organizations more rapidly respond to 211change in the TLS ecosystem, such as changes to certificate algorithms or 212support for new protocols. 213 214Another option is to request that the publicly-trusted CA not log the 215certificate. This will prevent this certificate from being trusted by default, 216but organizations that manage their devices or users can override this through 217[Enterprise Policies](#Enterprise-Policies) to enable these certificates to be 218trusted for users in their Enterprise. 219 220Finally, organizations may manage their own PKI in-house, using CA 221software such as [CFSSL](https://github.com/cloudflare/cfssl), [Boulder](https://github.com/letsencrypt/boulder), 222[EJBCA](https://www.ejbca.org/) or 223[Active Directory Certificate Services](https://msdn.microsoft.com/en-us/library/ff630887.aspx). 224Managing certificates in-house may be more complex and security risky, but 225offers an alternative solution to partnering with a certificate provider. 226 227### Legacy CAs 228 229Some Enterprises rely on Certificate Authorities that have not been audited to 230the same standard as other CAs or been operated to the same security 231requirements. These CAs would not be trusted in new products, nor other root 232programs, but may be trusted on one or more platforms that Chrome runs on. 233Because they are trusted by default, they are subject to the Chrome's policies 234on requiring CT, but due to their legacy status, may not be prepared. While the 235requirement to disclose new certificates via Certificate Transparency has been 236communicated, some may not do so, causing their new certificates to not be 237trusted. This is most common with CAs run by governments, as they rarely meet the 238required security standards of a widely-trusted CA. 239 240Organizations that need to use certificates from these CAs should be aware 241that their certificates will not be trusted if they do not support CT, and so 242should look for CAs that do support CT. Alternatively, supporting CT via TLS 243may be the only way to ensure these certificates continue to work, but that 244requires the Enterprise constantly keep track of changes regarding Certificate 245Transparency. 246 247Organizations that need to trust certificates from these CAs, such as when 248talking to other organizations that need to use these CAs, can configure 249[Enterprise Policies](#Enterprise-Policy) for users in their organization, 250which will allow trust in these certificates. As these only apply to Enterprise 251users, these policies are not suitable for making these certificates trusted 252more widely. 253 254### Enterprise Policies 255 256Several Chrome-specific policies exist that allow Enterprises to configure 257their machines or users to disable Certificate Transparency for certain cases. 258These policies are documented in the 259[master policy list](https://cloud.google.com/docs/chrome-enterprise/policies), 260but detailed further below. 261 262#### CertificateTransparencyEnforcementDisabledForUrls 263 264This [policy](https://cloud.google.com/docs/chrome-enterprise/policies/?policy=CertificateTransparencyEnforcementDisabledForUrls) 265has been available since Chrome 53, and allows for disabling Certificate 266Transparency enforcement for a certain set of domains or subdomains, without 267disabling Certificate Transparency altogether. 268 269If you wish to disable CT for a given hostname, and all of its subdomains, then 270the domain is simply entered into the list. For example, `example.com` will 271disable CT for `example.com` and all subdomains. 272 273If you wish to disable CT only for a given hostname, but wish to ensure that 274subdomains will still have CT enabled, then prefix the domain with a leading 275dot. For example, `.example.com` will disable CT for `example.com` exactly, 276while leaving it enabled for subdomains. 277 278#### CertificateTransparencyEnforcementDisabledForCas 279 280This [policy](https://cloud.google.com/docs/chrome-enterprise/policies/?policy=CertificateTransparencyEnforcementDisabledForCas), 281available since Chrome 57, allows for disabling Certificate Transparency 282enforcement if certain conditions are met in the trusted certificate chain. 283This allows disabling CT without having to list all of the domain names, but 284only for certificates issued to a specific organization. 285 286Certificates are specified in this policy by applying Base64 to a hash of their 287subjectPublicKeyInformation, as well as specifying the hash algorithm used. 288This format is very similar to that used by 289[HTTP Public Key Pinning](https://tools.ietf.org/html/rfc7469) (HPKP), so that 290sites can use the same [examples](https://tools.ietf.org/html/rfc7469#appendix-A) 291or [tools](https://report-uri.com/home/pubkey_hash) used to generate HPKP 292hashes to determine how to configure the policy. Note that while both use 293Base64, an HPKP hash will be in the form `pin-sha256="hash"`, while the policy 294will be in the form `sha256/hash`. 295 296To disable Certificate Transparency for these certificates, the certificate 297must match one of the following conditions: 298 2991. The hash specified is of the server certificate's subjectPublicKeyInfo. 3002. The hash specified is of an intermediate CA, and that intermediate CA has 301 a nameConstraints extension with one or more directoryNames in the 302 permittedSubtrees of that extension. 3033. The hash specified is of an intermediate CA, that intermediate CA contains 304 one or more organizationName (O) attribute in the subject, and the server 305 certificate's has the same number of organizationName attributes, with 306 byte-for-byte identical values, in the same exact order. 307 308#### CertificateTransparencyEnforcementDisabledForLegacyCas 309 310This [policy](https://cloud.google.com/docs/chrome-enterprise/policies/?policy=CertificateTransparencyEnforcementDisabledForLegacyCas), 311available since Chrome 67, allows for disabling Certificate Transparency 312enforcement for certain legacy CAs that have not adopted modern security and 313audit requirements required of publicly-trusted CAs. This is particularly 314tailored towards CAs that are trusted on some platforms that Chrome runs on, 315but are not trusted on ChromeOS or Android, due to not meeting the necessary 316security requirements. 317 318CAs are specified in this policy by applying Base64 to a hash of their 319subjectPublicKeyInformation, the same as in 320[CertificateTransparencyEnforcementDisabledForCAs](#CertificateTransparencyEnforcementDisabledForCas). 321However, these CAs must also be recognized as Legacy CAs in the 322[`/net/data/ssl/root_stores/root_stores.json`](/net/data/ssl/root_stores/root_stores.json) 323file, which means that they are not trusted on ChromeOS or Android, but are 324trusted on another platform that Chrome runs on. 325 326This policy is the riskiest of the three Enterprise policies, in that such 327legacy CAs can represent the greatest security threat to an organization, as 328they lack either the audits or compliance with industry best practice and root 329store requirements. Enterprises should only enable this policy if no other 330option meets their needs. 331 332## Certificate Transparency for Chrome/Chromium developers 333 334### //net Interfaces 335 336Support for Certificate Transparency in //net is made up of two core 337interfaces: 338 339* [`CTVerifier`](/net/cert/ct_verifier.h): Responsible for extracting the 340 CT information (SCTs) from the certificate, the OCSP response, and the 341 TLS handshake, validating the signatures against a set of known/configured 342 CT logs, and validating that the SCTs match the certificate provided. 343* [`CTPolicyEnforcer`](/net/cert/ct_policy_enforcer.h): Responsible for 344 taking the extracted, verified SCTs and applying 345 application/embedder-specific policies to determine whether the SCTs are 346 "good enough" (meet application requirements). 347 348In addition to these two core classes, configuration and support for CT-related 349behaviours is expressed via the 350[`TransportSecurityState`](/net/http/transport_security_state.h). The 351`TransportSecurityState` has methods for exposing support and policies for 352[`Expect-CT`](https://tools.ietf.org/html/draft-ietf-httpbis-expect-ct) and 353for embedder-specific overrides via the 354`TransportSecurityState::RequireCTDelegate`. 355 356### Supporting Certificate Transparency for Embedders 357 358While Chromium has implemented support for Certificate Transparency for a 359number of years, it would not block connections unless there was a known 360security issue. For example, certificates that were intended to be EV, but 361were not disclosed properly, simply would have their EV status removed, while 362the connection should still continue. 363 364However, as Google Chrome looks to roll out a more rigorous enforcement of 365Certificate Transparency, by enforcing that newly-issued certificates are 366disclosed as a condition of being trusted, the risks to the CA and CT 367ecosystem significantly increase if embedders implement CT without the ability 368for reliable, rapid updates, keeping track with ongoing development in the 369main tree and reliably delivering security updates on the same cadence as 370Chromium branches and Google Chrome releases. 371 372For this reason, the CT implementation is undergoing a refactoring to reduce 373those risks through code and implementation. As a result, Chromium embedders 374will **NOT** have CT enforcement enabled by default, and are **NOT** encouraged 375to manually enable it at this time. 376 377Distributors of products that embed Chromium sources are encouraged to 378participate in the 379[[email protected]](https://groups.google.com/a/chromium.org/forum/#!forum/ct-policy) 380discussion group, which involves a variety of stakeholders in the CT ecosystem 381for discussing matters of policy and implementation, in order to understand 382the risks and participate in solutions. Face-to-face summits are periodically 383held to gather key stakeholders together to work through these issues, helping 384root programs, CAs, log operators, and the overall PKI community develop 385consistent, interoperable, secure, and reliable policies and implementations. 386