Adding Expect-CT and Expect-Staple entries to the HSTS Preload List

Two of the new reporting features in https://report-uri.com currently require additions to the HSTS Preload List in Chromium. Here's a quick guide on how to request your site be added.


Update 2nd May: I wrote this blog some time ago and have only just published it now. I'm not sure Chrome are accepting entries to the preload list at present, but the article contains some interesting technical points and I wanted to publish it!


The HSTS Preload List

If you aren't familiar with HSTS you should start out by reading my blog HSTS - The missing link in Transport Layer Security and the blog specifically on HSTS Preloading. You can also get links to further information and details on my HSTS Cheat Sheet including a link to the actual HSTS Preload List itself. This is the list that we will be making an update to and you don't need to be HSTS preloaded in order to add your Expect-CT and/or Expect-Staple entry.


Adding Expect-CT and/or Expect-Staple

To make a change to the preload list you will have to submit a change to the Chromium source to add or update your entry as appropriate. To start with, you need to check the Chromium source out but to avoid pulling the whole code base down you can pull down just the part required using this script. I'm creating a new directory to work out of but you can do this wherever you like.


mkdir ~/chromium
cd ~/chromium
wget https://gist.githubusercontent.com/lgarron/73cf22ed381ef9786739ee5abd816c59/raw/241c176168d9cbec8c2b5e9e90a81da77d518f76/checkout-chromium-preload-list.sh
chmod +x checkout-chromium-preload-list.sh

Now the script is ready to go we can checkout the Chromium source and change into the folder.


./checkout-chromium-preload-list.sh
cd chromium-hsts

The file we need to change is now ready to be edited and you can use any editor of your choice.


nano net/http/transport_security_state_static.json

The file is pretty big and the changes you need to make will depend on your current listing within the preload list, if you have one. If you already have an entry and it was submitted through the HSTS preload site you will need to find it and cut the line out to paste it into the manual entries section. If you don't already have an entry you can keep following and create your new one to put into the manual entries section. This is what an existing entry will look like and what you need to cut out if you have one.


{ "name": "scotthelme.co.uk", "include_subdomains": true, "mode": "force-https" },

Either building off your existing entry or creating a new one, you need to add the appropriate fields for the feature you want to enable. These are the values you need to add for Expect-CT and Expect-Staple respectively.


"expect_ct": true, "expect_ct_report_uri": "https://scotthelme.report-uri.com/r/d/ct/reportOnly", "include_subdomains_for_expect_ct": true

"expect_staple": true, "expect_staple_report_uri": "https://scotthelme.report-uri.io/r/d/staple/reportOnly", "include_subdomains_for_expect_staple": true

If you had an existing HSTS preload entry like I did then you will end up with something like this if you include both Expect-CT and Expect-Staple.


{ "name": "scotthelme.co.uk", "include_subdomains": true, "mode": "force-https", "expect_ct": true, "expect_ct_report_uri": "https://scotthelme.report-uri.com/r/d/ct/reportOnly", "include_subdomains_for_expect_ct": true, "expect_staple": true, "expect_staple_report_uri": "https://scotthelme.report-uri.com/r/d/staple/reportOnly", "include_subdomains_for_expect_staple": true},

This new entry will now need to be placed in the manual entries section. You can find the start of this section by searching for // START OF MANUAL ENTRIES and the end of the section is marked with // END OF MANUAL ENTRIES. Place your new entry at the end of this section. Once your changes are saved you need to setup Git for the current repo if you don't have a global config or it's not appropriate for this change.


git config user.name "Scott Helme"
git config user.email "[email protected]"
git config core.autocrlf false
git config core.filemode false
git config branch.autosetuprebase always
git config gerrit.host true

The email address you use will need to be a Google account and you need to fetch credentials for it to work. Go to this link and select the appropriate Google account if you have multiple, it will then present you with the commands you need to run to configure git which I've outlined here:


touch .gitcookies
chmod 0600 .gitcookies

git config http.cookiefile .gitcookies

tr , \\t <<\__END__ >>.gitcookies
*stuff here*
__END__

I've modified the commands here to remove the global setting and also to put the .cookies file in the local directory instead of my home directory. Feel free to update your commands if you wish. With that, commit your changes.


git commit -a

The final step is to download depot_tools that you will need to submit the change.


git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
export PATH=`pwd`/depot_tools:"$PATH"

You're all set and ready to upload the change for review!


git cl upload -r [email protected]

That command will upload your change and is flagging it for review by Lucas Garron, the current HSTS Preload List maintainer. The command will also give you an address where you can review the change you submitted. You will need to go to the link, login with the Google account you used and click 'Start Review' otherwise your change can't be progressed. You can see my recent change here. With the change submitted and pending review, you now need to prove that this request came from the genuine owner/admin of the domain. This is really easy to do and just requires a simple DNS TXT record to approve the request. The format is outlined in the section for Report URI customers on the HSTS Preload List Wiki and shown below.


example.com.    ...   "Please preload example.com for [Expect-CT/Expect-Staple/Expect-CT and Expect-Staple] using [subdomain].report-uri.com"

Which gives me a record that looks like this.


scotthelme.co.uk.       299     IN      TXT     "Please preload scotthelme.co.uk for Expect-CT and Expect-Staple using scotthelme.report-uri.com"

Update the record for your own domain and either or both of the features you're enabling. Of course you should claim your own vanity subdomain on Report URI and make sure it's one you like because it takes some time for the change to reach Chromium and then for you to change it again at a later date. Please save Lucas the trouble and make sure it's one you will keep! You can check your TXT records easily here.

All there is to do now is wait. Lucas will review the change and if you've done everything right it will most likely hit the next major version of Chrome! Happy preloading :-)