From 13feb3f7680723e9ab9c3a889eeeb5f25cc97490 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Kooman?= Date: Wed, 1 Jun 2016 08:54:07 +0200 Subject: initial commit --- posts/indiecert.md | 265 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 265 insertions(+) create mode 100644 posts/indiecert.md (limited to 'posts/indiecert.md') diff --git a/posts/indiecert.md b/posts/indiecert.md new file mode 100644 index 0000000..8f5fedc --- /dev/null +++ b/posts/indiecert.md @@ -0,0 +1,265 @@ +--- +title: Introducing IndieCert +published: 2015-02-02 +modified: 2015-03-08 +--- + +**More feedback is required before this document can be considered finished. See "Issues" section below.** + +Authenticating to web servers with a client certificate, installed in the +user's browser, is unfortunately not widely used. They are convenient and safe +to use once the initial hurdle of installing them is taken. + +There is now a Proof of Concept instance! Check it out [here](https://indiecert.net)! + +The main benefit is easy and secure authentication. There is no need to provide +a password to any service, only the URL to your home page. So there is no +chance you will leak your password to some service. + + + +In addition, this proposal describes a way to make the use of client certificates +feasible: + +1. A self-signed CA is used instead of a 'browser trusted' CA to issue the client certificates, this works without browser warnings; +2. Users authorize the certificates by publishing the certificate fingerprint on their home page allowing to claim ownership of a URL and by authenticating with the certificate directly; +3. Allow identity (certificate) linking using the user's home page address to allow registration of multiple fingerprints to support multiple devices and browsers. + +A possible drawback is that many users do not have a home page anymore. They +have a Facebook profile or a Twitter account, but no home page. However, this +is not relevant for [IndieWeb](https://indiewebcamp.com/) as all +users should have their own home page running on their own domain anyway :) + +As a fallback it is possible to allow authenticating using existing social +networks, similar to [IndieAuth](https://indieauth.com), instead +of using the client certificates. Some browsers and operating systems +unfortunately do not support easy client certificate enrollment. + +keep calm and use certificates + +### Protocol for Relying Parties + +The protocol follows the protocol proposed for IndieAuth. The protocol is +based on the IndieAuth protocol and aims to be compatible with it. + +#### Request Authentication + +The service redirects the user to `https://indiecert.net/auth` to +start the authentication phase. Two parameters need to be specified: + +- **redirect_uri**: + - the URL the browser should be redirected back to after the authentication is successful. This MUST be a valid HTTPS URL; +- **me**: + - the URL to the user's home page (see [Retrieving the User's Home Page](#retrieve_home_page)); + +##### Example +Below is an example of a browser redirect. The process can also be initiated +with a `
` submit using the `GET` method. + +``` +HTTP/1.1 302 Found +Location: https://indiecert.net/auth?redirect_uri=https://example.org/callback&me=https://tuxed.net/fkooman +``` + +IndieCert will at this point take care of the authentication and optional +enrollment process if that was not already done. + +#### Authentication Response + +IndieCert will redirect the browser back to the `redirect_uri` +specified in the authentication request after the user is authenticated at +IndieCert. + +##### Example + +``` +HTTP/1.1 302 Found +Location: https://example.org/callback?code=wW3OLXJZn35d7zFwg9YGmWti +``` + +#### Verification Request + +The `code` parameter can now be used to request the claimed user +identity. The following parameters are required: + +
+
`code`
+
the code obtained in the authentication response query parameter `code`.
+
`redirect_uri`
+
the URL the browser was redirected back to after the successful authentication;
+
+ +Now a HTTP `POST` can be used to obtain the user's (normalized) home +page URL: + +``` +POST /auth HTTP/1.1 +Host: indiecert.net +Content-Type: application/x-www-form-urlencoded +Accept: application/json + +redirect_uri=https%3A%2F%2Fexample.org%2Fcallback&code=wW3OLXJZn35d7zFwg9YGmWti +``` + +The response will be formatted as JSON indicating the actual user home page in +the `me` parameter. + +This is the identity that MUST be used by the relying party to identify the +user as it could differ from the initial `me` specified by the user, +e.g.: redirects were followed to reach the user's home page. + +``` +HTTP/1.1 200 OK +Content-Type: application/json +Cache-Control: no-store +Pragma: no-cache + +{ + "me": "https://www.tuxed.net/fkooman/" +} +``` + +In case there was a failure in verifying the code, e.g. it was already used, or +not valid the following response can be expected: + + +``` +HTTP/1.1 400 Bad Request +Content-Type: application/json +Cache-Control: no-store +Pragma: no-cache + +{ + "error":"invalid_request" +} +``` + +### Protocol for the IndieCert Service + +The IndieCert service has to deal with certificates, issuing, installing and +verifying them. The most convenient method is to use the HTML +`` tag. This makes the browser generate a private key +and certificate request (SPKAC) that is then sent to the service for signing. +The service will sign this with the CA generated for this particular IndieCert +instance. The signed certificate is sent back to the client and (automatically) +imported in the browser certificate store. + +After this, the certificate can be used to authenticate to the IndieCert +service, but it still needs to be linked to the URL of the user's home page. +This can be done by using the `rel="me"` attribute in a +`` header tag or `` body tag. + +``` + +``` + +Once the user has placed this HTML element on their home page the URL it will +be found when the IndieCert instance will fetch the URL and extract all +`` and `` tags to look for the +`rel="me"` attribute. The fingerprint of the client certificate +used to authenticate to IndieCert needs to be listed on the home page. +After that, the URL of the home page will be used as an accepted identifier. + + + +#### Retrieving the User's Home Page + +The user's home page MUST be fetched over HTTPS only, MUST follow redirects and +MUST NOT have any HTTP URLs in its redirect path. If the URL does not start +with `https://` it MUST be added by IndieCert. If a URL starts with +`http://` or is otherwise invalid it MUST be rejected. The final +URL, the URL that returns a `200 OK` status, MUST be used in the +response to the verification request, this is the normalized home page URL. + +For example the user provides `tuxed.net/fkooman`. IndieCert makes +this `https://tuxed.net/fkooman` and starts the fetching process. It +is then redirected to `https://www.tuxed.net/fkooman` and then to +`https://www.tuxed.net/fkooman/`. The claimed identity thus becomes +`https://www.tuxed.net/fkooman/` and this value is returned in +response to the verification request. + +### Identity Linking + +One of the benefits of publishing fingerprints on the user's home page is that +additional client certificate fingerprints can easily be added to the home page +to allow those certificates to claim the same identity. + +``` + + + + + +``` + +Certificate revocation is done by removing the entry from the home page and it +can no longer be used to claim the identity. + +### Fingerprint Generation + +The fingerprint of the certificate is generated by calculating the SHA-256 hash +over the DER encoded certificate and base64url encoding the resulting binary +string according to RFC 6920 "Naming Things with Hashes" and RFC 4648 +"The Base16, Base32, and Base64 Data Encodings". An example of calculating a +fingerprint in PHP: + +``` +