1# Root Stores 2 3This directory contains information about the contents of various platforms' 4and libraries trust stores, used for assessing risk and interoperability. Only 5certificates trusted for SSL/TLS issuance are included. 6 7As updating these stores requires manual curation, and as histograms require 8being checked in, the generated files are not part of the build process, but 9instead updated via [update_root_stores.py](update_root_stores.py) to update 10[//net/cert/root_cert_list.h](/net/cert/root_cert_list.h), and using 11[//tools/metrics/histograms/update_net_trust_anchors.py](/tools/metrics/histograms/update_net_trust_anchors.py) 12to update the associated histograms. 13 14## Format 15 16Note: All SHA-256 hashes are stored as hex-encoded strings. 17 18``` json 19 20{ 21 "certificates": { 22 "sha256_of_certificate": [ 23 "root_store_1", 24 "root_store_2", 25 ], 26 }, 27 "last_spki_id": integer_used_for_histogram_purposes, 28 "spkis": { 29 "sha256_of_subjectPublicKeyInfo": { 30 "id": integer_used_for_histogram_purposes, 31 "fingerprints": [ 32 "sha256_of_trust_anchor_with_this_spki", 33 "sha256_of_another_trust_anchor_with_this_spki", 34 ] 35 } 36 } 37} 38``` 39 40The choice of this format was to allow for the following scenarios: 41 42* Easy generation of histogram enumerations for associated SPKIs 43* The ability to prune certificates (and SPKIs) as Chromium platforms are 44 deprecated. 45* The ability to update the root store metadata effectively, such as via JSON 46 Patch, while maintaining the stable ordering necessary for histogram code. 47 48## Root Store Sources 49 50### Android 51 52Prior to Android N (Nougat), the set of trust anchors included in Android 53were provided in the [platform/libcore](https://android.googlesource.com/platform/libcore) 54repository, under `luni/src/main/files/cacerts` 55 56Beginning with Android N, the set of trust anchors included in Android is 57provided in the [platform/system/ca-certifcates](https://android.googlesource.com/platform/system/ca-certificates) 58repository, under `files`. 59 60### Apple macOS 61 62The set of root certificates for macOS is available at https://opensource.apple.com/. 63 64Since macOS 10.4 (Tiger), the set of root certificates included is available 65within the `security_certificates` package, which is independently versioned 66from other packages in macOS. Only revisions since 10.9 whose package contents 67had changed were included for consideration. 68 69Additional restrictions upon trusted CAs are maintained both within the code 70of Security.framework and through additional plist expressions, such as for 71allowlisted certificates. However, these were not consulted, as they're not 72applicable to this use case. 73 74### Mozilla NSS 75 76Mozilla NSS independently versions the set of included root certificates from 77the NSS library version. The root package is known within the source as 78`nssckbi`, maintained in `lib/ckfw/builtins`. The version can be extracted 79from `nssckbi.h`, while the trust store is maintained within `certdata.txt`. 80 81Additional restrictions upon trusted CAs are maintained both within the code 82of NSS and Mozilla Firefox; however, these were not consulted, as they're not 83applicable to this use case. 84 85### Microsoft Windows 86 87Microsoft Windows maintains its root certificates in two locations - within 88a resource of `crypt32.dll`, shipped with the appropriate Windows release, and 89through the Automatic Root Update (AuthRoot) mechanism, served at 90http://www.download.windowsupdate.com/msdownload/update/v3/static/trustedr/en/authroot.cab 91 92The contents of the cab file are a [PKCS#7 trust store](http://unmitigatedrisk.com/?p=259), 93with attribute OIDs that match to `PROP_ID` documented in `wincrypt.h` and, 94less exhaustively, on [MSDN](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376079(v=vs.85).aspx) 95 96Additional restrictions upon trusted CAs are maintained as properties within 97the STL; however, these were not consulted, as they're not applicable to this 98use case. 99 100Tools that can help get this data: 101 102* https://github.com/robstradling/authroot.stl 103* https://github.com/zmap/rootfetch 104