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

Mattias Geniar, Wednesday, March 16, 2016

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).



Hi! My name is Mattias Geniar. I'm a Support Manager at Nucleus Hosting in Belgium, a general web geek & public speaker. Currently working on DNS Spy & Oh Dear!. Follow me on Twitter as @mattiasgeniar.


Share this post

Did you like this post? Will you help me share it on social media? Thanks!

Comments

Nicolas Hoizey Thursday, March 24, 2016 at 12:33 - Reply

I already use a .well-known directory for some files, it helps keep the site root clean:
https://github.com/nhoizey/nicolas-hoizey.com/tree/master/.well-known

But I also have a few rewrite rules for browsers looking for some of these files on the root:
https://github.com/nhoizey/nicolas-hoizey.com/blob/master/.htaccess#L724-L748


Mattias Geniar Saturday, December 10, 2016 at 09:48 - Reply

Sure, no harm in doing so. Delete it if you want.


Leave a Reply

Your email address will not be published. Required fields are marked *

Inbound links