The “.well-known” directory on webservers (aka: RFC 5785)

Want to help support this blog? Try out Oh Dear, the best all-in-one monitoring tool for your entire website, co-founded by me (the guy that wrote this blogpost). Start with a 10-day trial, no strings attached.

We offer uptime monitoring, SSL checks, broken links checking, performance & cronjob monitoring, branded status pages & so much more. Try us out today!

Profile image of Mattias Geniar

Mattias Geniar, March 16, 2016

Follow me on Twitter as @mattiasgeniar

I first came across the concept of the directory named ‘.well-known’ when automating Let’s Encrypt, the free SSL certificate authority. It didn’t strike me as abnormal to have a validation happen via an HTTP or HTTPS GET request. Those Let’s Encrypt validation URLs usually point to site.tld/.well-known/acme-challenge/random-key.txt.

At first I thought this was just the random URL used by Let’s Encrypt, but today I learned there’s more to it. Allow me to introduce RFC-5785.

It is increasingly common for Web-based protocols to require the

discovery of policy or other information about a host (“site-wide

metadata”) before making a request.

[…]

When this happens, it is common to designate a “well-known location”

for such data, so that it can be easily located.

[…]

To address this, this memo defines a path prefix in HTTP(S) URIs for

these “well-known locations”, “/.well-known/".

RFC-5785

The directory location /.well-known isn’t a coincidence, it’s the result of a carefully considered RFC. This directory can be used for all kinds of information discovery.

For instance, Let’s Encrypt uses a subdirectory called /.well-known/acme-challenge/, where ‘ACME’ stands for Automated Certificate Management Environment.

There’s a Do Not Track policy (DNT) that uses a similar file in that directory for validation: /.well-known/dnt-policy.txt.

There are a couple of webservers configurations that prevent opening directories that start with dot “.". The reasoning behind it is that it might give away sensitive information, like a .git or .svn directory (which probably shouldn’t even be on your webserver in the first place).

However, this RFC for the .well-known directory make it clear that at least this particular directory should be allowed to be accessed (not in a directory-listing sense, but for direct file access).



Want to subscribe to the cron.weekly newsletter?

I write a weekly-ish newsletter on Linux, open source & webdevelopment called cron.weekly.

It features the latest news, guides & tutorials and new open source projects. You can sign up via email below.

No spam. Just some good, practical Linux & open source content.