Web Signature Directory v0

Ariadne Identity Related Specifications

Web Signature Directory v0

Table of contents

Ariadne Alias Specification

Author: Yarmo Mackenbach <yarmo@keyoxide.org>
Version: 0
Published: 2022-11-22
Last updated: 2022-11-24

Abstract

This specification describes a service to locate cryptographic signatures using the HTTP protocol. It also provides a method of secured uploading and updating of new signatures by the holder of the cryptographic key.

Status

This version of the specification is a draft. It is not recommended to base implementations on this version.

Copyright (c) 2022 Yarmo Mackenbach. All rights reserved.

1. Introduction

This specification describes a method to store and publish cryptographic signatures and their message, and a protocol through which to upload and update them.

This specification is largely inspired by and based on the OpenPGP Web Key Directory specification [draft-koch-openpgp-webkey-service-15].

1.1. Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

2. Web Signature Directory

Cryptographic signatures belong the "public side" of asymmetric cryptography, information that can be publicly shared without risking exposure of secret information. Yet, there exists no infrastructure for the publishing of cryptographic signatures.

One use-case for publicly-accessible cryptographic signatures are Ariadne Identities [Ariadne Identity Specification] stored inside cryptographic signatures. Ariadne Identities stored inside OpenPGP keys can easily be accessed through the HKP or the Web Key Directory protocol. A similar protocol is needed to access cryptographic signatures and their message through a simple identifier.

Web Signature Directory should be usable by both people with a simple web server that are only interested in the publishing part of this specification, and service providers that host a large number of cryptographic signatures.

2.1. Signature Discovery

2.1.1. WSD identifier

Cryptographic signatures accessible through the Web Signature Directory are identified by a URI as follows:

wsd:domain-part:local-part

where the domain-part is the domain that hosts the signature and the local-part is the unique identifier of the signature for that domain.

Since the local-part is directly used to access the cryptographic signature, the local-part is an arbitrary string. To allow the mapping of incoming HTTP requests directly to the file system, the characters used in the identifier are limited to alphanumerical characters and including the dash ("-"), underscore ("_"), at ("@") and dot (".") symbols.

2.1.2. HTTP requests

Cryptographic signatures can be fetched through GET HTTP requests. The URL is constructed as follows:

https://domain-part/.well-known/wsd/id/local-part/resource

where domain-part and local-part map directly to the URI identifier described above, and resource is the requested resource.

The following resources must be published by the server:

  • "message": the original message
  • "signature": the signature of the message
  • "protocol": the cryptographic protocol used to generate the signature

The server MAY publish the following resources:

  • "publickey": the public key to verify the signature
  • "json": a single JSON object that contains the resources mentioned above as key-value pairs

Optional resources not published must return a 404 NOT FOUND HTTP response.

If no resource is provided, the service provider MAY choose to serve a browser-friendly render of the message and the signature.

Currently defined protocols are:

3. Web Signature Discovery Update Protocol

Uploading and updating signatures is done through POST HTTP requests. The protocol is designed to work with plain HTML forms without requiring JavaScript. Service providers may require additional authentication methods that may necessitate the use of JavaScript.

The URL for the POST HTTP requests is constructed as follows:

https://domain-part/.well-known/wsd/post

The HTTP request body MUST be encoded as application/x-www-form-urlencoded and MUST contain the following fields:

  • "message": the message to sign
  • "signature": the signature of the message
  • "protocol": the cryptographic protocol used to generate the signature
  • "header": the header text containing instructions for the server
  • "header-signature": the signature of the header text

The HTTP request body MAY contain the following field:

  • "publickey": the public key to verify the signature

Note that it is RECOMMENDED to include the public key unless there already exists key discovery infrastructure for the cryptographic protocol in question, such as HKP and WKD for OpenPGP keys.

All values MUST be plaintext and served as such at their respective HTTP locations.

The header and the header-signature fields SHOULD be discarded after the upload is complete.

3.1. The header field

The header field has a plaintext newline-separate value that MUST contain the following properties:

  • "timestamp": the UNIX timestamp of the request

The server SHOULD only act on HTTP requests for which the "timestamp" value is no older than 30 seconds.

The header field MAY contain the following properties:

  • "wsd-identifier": the WSD identifier of the existing signature this upload will replace

If no signature identified by the provided WSD identifier exists, the upload MUST be aborted and return a 400 BAD REQUEST HTTP response.

If such a signature already exists but the uploaded signature is signed by a different key, the upload MUST be aborted and return a 400 BAD REQUEST HTTP response.

Example:

timestamp: 1669125747
wsd-identifier: wsd:wsd.tld:8k75q_e9Koh1

3.2. The HTTP response

The HTTP response MUST contain the following headers:

  • "Wsd-Identifier": the WSD identifier assigned to the uploaded signature
  • "Location": the URL at which to find the uploaded signature

It is up to the service provider to decide on the naming of signatures. Signature names could be:

  • based on the cryptographic key, meaning every key can only have a single signature
  • based on the signature hash
  • randomly generated

4. Considerations

WSD servers MUST use HTTPS for all the public HTTP locations.

WSD servers SHOULD implement forms of rate limiting to limit abuse.

WSD servers SHOULD NOT index the WSD well-known directory.

References

[Ariadne Identity Specification] https://ariadne.id

[draft-koch-openpgp-webkey-service-15] https://www.ietf.org/archive/id/draft-koch-openpgp-webkey-service-15.html

[minisign] https://jedisct1.github.io/minisign/

[openssh] https://www.openssh.com/

[RFC2119] https://www.rfc-editor.org/rfc/rfc2119

[RFC4880] https://www.rfc-editor.org/rfc/rfc4880

Appendix A. Sample Protocol Run

A.1. Basic signature self-hosting

Assuming the domain alice.tld, its holder Alice and her minisign key:

# Public key
untrusted comment: minisign public key EB0CB14BFA64DD15
RWQV3WT6S7EM63OEQfwnDBpj7QN/O3Ki05VHLpKwX9QFEejqD7Id09Vp

# Private key
untrusted comment: minisign encrypted secret key
RWRTY0Iyp46U/LudMVaFBbgUgcpw6rLewWXqX6vnsqoBa/eBxeYAAAACAAAAAAAAAEAAAAAAqSFU0iPmo0miS1rlOnmdtCXQhVrOFTq47yCddMBkxzok0yYbCP5vCc+wEhpdE+zSv6wkw9TP8/OeEiDFk/O5kUEBjBvXHOkouTB9copzNCgcdOZotXEkxcPRg7pe9tnmQXAXpOnUjiM=

Alice chooses 42 as the local-part of her WSD identifier. Her WSD identifier is:

wsd:alice.tld:42

The HTTP request to get the message:

GET /.well-known/wsd/id/42/message
Host: alice.tld
Content-Type: text/plain

The Answer to the Ultimate Question of Life, the Universe, and Everything.

The HTTP request to get the signature:

GET /.well-known/wsd/id/42/signature
Host: alice.tld
Content-Type: text/plain

untrusted comment: signature from minisign secret key
RUQV3WT6S7EM6xOSZNS31U5xoY15i7+oQmga+Wfrnssb6zU6MBiBn6I0cGp7HinhVCDWglFKA0fVdaRClTiWtJQCKO9K7XEpIw0=
trusted comment: timestamp:1669118142 file:message.txt hashed
T6JCzuqGHo2NO7heGkuPs25jZlZdCEIgLh3GiUVtsYZbdicH8YobGZN806e73fNsPbfEGAtlBtFlFkIehsBlAw==

The HTTP request to get the protocol:

GET /.well-known/wsd/id/42/protocol
Host: alice.tld
Content-Type: text/plain

minisign

The HTTP request to get the public key:

GET /.well-known/wsd/id/42/publickey
Host: alice.tld
Content-Type: text/plain

untrusted comment: minisign public key EB0CB14BFA64DD15
RWQV3WT6S7EM63OEQfwnDBpj7QN/O3Ki05VHLpKwX9QFEejqD7Id09Vp

As Alice updates her website directly through the file system, she may choose to not implement the Web Signature Discovery Update Protocol.

A.2. WSD Service Provider

Assuming the domain wsd.tld operated by a WSD service provider, a person named Alice and her minisign key:

# Public key
untrusted comment: minisign public key EB0CB14BFA64DD15
RWQV3WT6S7EM63OEQfwnDBpj7QN/O3Ki05VHLpKwX9QFEejqD7Id09Vp

# Private key
untrusted comment: minisign encrypted secret key
RWRTY0Iyp46U/LudMVaFBbgUgcpw6rLewWXqX6vnsqoBa/eBxeYAAAACAAAAAAAAAEAAAAAAqSFU0iPmo0miS1rlOnmdtCXQhVrOFTq47yCddMBkxzok0yYbCP5vCc+wEhpdE+zSv6wkw9TP8/OeEiDFk/O5kUEBjBvXHOkouTB9copzNCgcdOZotXEkxcPRg7pe9tnmQXAXpOnUjiM=

The HTTP request to publish Alice's first signature:

POST /.well-known/wsd/post
Host: wsd.tld
Content-Type: application/x-www-form-urlencoded

message=And+the+clocks+were+striking+twelve.&signature=untrusted+comment%3A+signature+from+minisign+secret+key%0D%0ARUQV3WT6S7EM6ysa2O%2FHz7NW3XOQxQQOso5YkOUFFOPc7bjHoLM3Av1UenznN5eFg5lLz%2FoCkWTnQUI6rtwUkBy%2BRewH%2FpC88wk%3D%0D%0Atrusted+comment%3A+timestamp%3A1669125390%09file%3Amessage.txt%09hashed%0D%0A7dA7CDa4mNvxarvpnsnSCSaXPLLvbvLHMRU0puqfGwtbJxTEBNwGNlDyDKlUA9hj4yaylNHURAEEfPR0OvleDQ%3D%3D&header=timestamp%3A+1669125390&header-signature=untrusted+comment%3A+signature+from+minisign+secret+key%0D%0ARUQV3WT6S7EM68firzxIKT4bh1lMwDmXEPfSnjLRzwJdyzudqBKUCpD0I68u2mulPUkz4dyR9Qn3Uq0BDknidfLR9ZbCT7F51wU%3D%0D%0Atrusted+comment%3A+timestamp%3A1669125430%09file%3Aheader.txt%09hashed%0D%0ATKPyKTEbtx8fUhCtCLYjpudlgjUnXE9ZaZWsW42J%2BpOX2mAJa4JRi%2FRF53ws2MLzYHUKTTe0KFOKzqDvor9OCw%3D%3D

Response:
201 CREATED
Wsd-Identifier: wsd:wsd.tld:8k75q_e9Koh1
Location: https://wsd.tld/.well-known/wsd/id/8k75q_e9Koh1/signature

The HTTP request to publish Alice's second signature:

POST /.well-known/wsd/post
Host: wsd.tld
Content-Type: application/x-www-form-urlencoded

message=But+some+animals+are+more+equal+than+others.&signature=untrusted+comment%3A+signature+from+minisign+secret+key%0D%0ARUQV3WT6S7EM6xULz3xQbOHtZ3ynwBY60ENv4pDSOnk%2BpVQXtZrCq%2BDab9RwzfQ5aEMb5J34XDqHRxUQHYJvhf3o94eLpEEAtQQ%3D%0D%0Atrusted+comment%3A+timestamp%3A1669125584%09file%3Amessage.txt%09hashed%0D%0AXxH69zurQ4m554UfJwqln5Q989xatQRW8PdWyABmFwvKaqKNWjL410TElC%2Bd5mVFVgTmfvoRX6hBamb7MIveCA%3D%3D&header=timestamp%3A+1669125584&header-signature=untrusted+comment%3A+signature+from+minisign+secret+key%0D%0ARUQV3WT6S7EM68firzxIKT4bh1lMwDmXEPfSnjLRzwJdyzudqBKUCpD0I68u2mulPUkz4dyR9Qn3Uq0BDknidfLR9ZbCT7F51wU%3D%0D%0Atrusted+comment%3A+timestamp%3A1669125633%09file%3Aheader.txt%09hashed%0D%0ADYe22m9pG%2FIOr7CjBW6C7f%2Bem4Vy8MmH0IzEQPqMQxasjcAjEefdxjZyKzGsQzvBwJcrrW90oi4dlXR7VAQuAQ%3D%3D

Response:
201 CREATED
Wsd-Identifier: wsd:wsd.tld:lEjG1TxYrv52
Location: https://wsd.tld/.well-known/wsd/id/lEjG1TxYrv52/signature

The HTTP request to update Alice's first signature:

POST /.well-known/wsd/post
Host: wsd.tld
Content-Type: application/x-www-form-urlencoded

message=And+the+clocks+were+striking+thirteen.&signature=untrusted+comment%3A+signature+from+minisign+secret+key%0D%0ARUQV3WT6S7EM6%2F0CF95Zsj96J0iGkNwTSqNHd0C4fYXLoV%2BkY0sBSjDtsPTy5H1%2FagIKtU%2Fi6sZbKFTta8rfRZpHt%2FkXknzPrQ0%3D%0D%0Atrusted+comment%3A+timestamp%3A1669125747%09file%3Amessage.txt%09hashed%0D%0ALJkxv65%2Fng7l3wJlhME7cb%2FTPmwIRc4GqLO2Ux3Utuq%2Bk3HODDN6GzDTVJ7c8BHHc14mrx%2BDIXSKRbwLGfNiBg%3D%3D&header=timestamp%3A+1669125747%0D%0Awsd-identifier%3A%20wsd%3Awsd.tld%3A8k75q_e9Koh1&header-signature=untrusted+comment%3A+signature+from+minisign+secret+key%0D%0ARUQV3WT6S7EM61ailqzNcITw5pydRilbb6aA1DPXg2Jn9co86sqRnqx952%2BvxKXvqtZEc5Vd2AzgF5zyVDrgspDhTWuSkxAGWgc%3D%0D%0Atrusted+comment%3A+timestamp%3A1669125817%09file%3Aheader.txt%09hashed%0D%0AFbbrejgoPbV5if6NEbfxAcpH2EtFTpd%2B1Xg4BQ1mYeTxbvCbaGDewspTK%2FOXeBvukFOpkCx%2B%2F%2FixkzYZkEQaBw%3D%3D

Response:
201 CREATED
Wsd-Identifier: wsd:wsd.tld:8k75q_e9Koh1
Location: https://wsd.tld/.well-known/wsd/id/8k75q_e9Koh1/signature

The HTTP request to get Alice's first message:

GET /.well-known/wsd/id/8k75q_e9Koh1/message
Host: wsd.tld
Content-Type: text/plain

And the clocks were striking thirteen.

The HTTP request to get Alice's second message:

GET /.well-known/wsd/id/lEjG1TxYrv52/message
Host: wsd.tld
Content-Type: text/plain

But some animals are more equal than others.