home -> developer -> YURL -> httpsy

WaterkenTM YURL

Authentication of TLS Upgrade Within HTTP/1.1


This specification defines a mechanism for authenticating an HTTP server based on the hash of its public key, instead of a trusted certificate from a certificate authority.


Before sending a request to a resource identified by an httpsy URL, a client MUST complete a mandatory upgrade to TLS/1.0. The client authenticates the server by constructing a valid certificate path to a certificate that is signed using a public key whose hash matches that given in the httpsy URL.


Design goals

  1. Existing Transport Layer Security (TLS) infrastructure is leveraged.
  2. Existing WWW infrastructure is leveraged.
  3. A migration path is provided for existing HTTPS client software.

Existing Transport Layer Security (TLS) infrastructure is leveraged

Reusing the existing and widely deployed TLS infrastructure minimizes the amount of specification, implementation, and evangelizing work required for deployment. [TLS]

Existing WWW infrastructure is leveraged

This specification defines a mechanism for use with the existing WWW infrastructure, and so needs to be compatible with it. This specification reuses the work done in RFC 2817 to meet this constraint. [RFC 2817]

Migrating existing HTTPS client software

Deploying upgraded client software takes time. A mechanism is provided for optionally falling back to the HTTPS protocol when the client software does not yet support the HTTPSY protocol. [RFC 2818] This option is at the sole discretion of the issuer of the URL.


This specification defines a mechanism for performing a TLS/1.0 protocol upgrade within HTTP/1.1, using the hash of the certificate issuer's public key for authentication, instead of a trusted certificate from a certificate authority.

The hash of the certificate issuer's public key is contained within the URL identifying the target resource. This specification defines a new URL scheme, httpsy, that provides the hash. This specification also defines a subset of the existing https URL scheme that provides the hash. The subset is identified by a userinfo field that begins with a '*'. An httpsy:// URL identifies a resource that MUST be accessed using the HTTPSY protocol. An https://* URL identifies a resource that SHOULD be accessed using the HTTPSY protocol, but MAY be accessed using the HTTPS protocol if the client does not implement HTTPSY.

The httpsy scheme

The httpsy scheme is used to locate network resources via the HTTP protocol and to authenticate servers using their public key hash. This section defines the scheme-specific syntax and semantics for httpsy URLs.

    httpsy_URL = "httpsy:" "//" key_id "@" host [ ":" port ] [ abs_path [ "?" query ]]
    key_id = MD5_hash | SHA1_hash
    MD5_hash = 26BASE32
    SHA1_hash = 32BASE32
    BASE32 = [a-zA-Z2-7]

If the port is empty or not given, port 80 is assumed. The host follows the grammar defined in RFC 2732. [RFC 2732]

Note that the syntax for an httpsy URL is the same as that for an http URL, except key_id replaces userinfo. The rules for forming an HTTP request for an httpsy URL are the same as those for an http URL. [HTTP]

The semantics are that the identified resource is located at the server possessing the private key corresponding to the public key whose hash is provided in the URL. The host is merely a hint as to how the server may be contacted.

Unlike the http scheme, the use of an IP address for the host is not discouraged. The redirection functionality of the HTTPSY protocol can substitute for the DNS. In the httpsy scheme, the host is like the address of the nameserver, rather than the address of the server. The address of a nameserver SHOULD be much more constant than that of a server.

The key_id is the base32 encoding of the cryptographic hash of the certificate issuer's public key. [base32] The public key is encoded in the DER encoding of the ASN.1 type 'SubjectPublicKeyInfo', as defined by the X.509 standard. [RFC 3279] The cryptographic hash algorithm is either MD5 or SHA-1. The hash algorithm used is determined based on the length of the produced hash. key_ids MUST be compared using a case-insensitive octet-by-octet comparison.

The https scheme *-subset

The https scheme *-subset is a hybrid scheme combining the properties of the httpsy and https schemes. This section defines the scheme-specific syntax and semantics for https *-subset URLs.

    https_URL = "https:" "//*" key_id "@" host [ ":" port ] [ abs_path [ "?" query ]]

When interpreted by an HTTPSY-aware client, the sematics for this scheme are the same as for the httpsy scheme.

When interpreted by an HTTPSY-unaware client, the sematics for this scheme are the same as for the https scheme. The *key_id@ portion of the URL MUST be ignored.

Issuing an https *-subset URL is only safe when the authentication results of both the HTTPSY and HTTPS protocols can be considered equivalent. In particular, it MUST be the case that the URL issuer has the private key for a PKI certified certificate for the host, and that the URL issuer is willing to trust the PKI. This trust requirement means that an https *-subset URL is not a YURL. [YURL]

The https *-subset is only provided as a temporary bridge to enable deployment of HTTPSY server applications during the rollout of HTTPSY client applications. A server that supports https *-subset URLs MUST also support httpsy URLs. Any resource identified by an https *-subset URL MUST also be identified by an httpsy URL constructed by changing the scheme and removing the '*' character.

The HTTPSY protocol

Before sending a resource request, the client MUST upgrade the connection to TLS/1.0 and authenticate the HTTP server using the provided public key hash. The mandatory upgrade is performed as specified in section 3.2 of RFC 2817. The upgrade request MUST additionally specify a Key-Identifier header that contains the public key hash taken from the resource's URL. The Key-Identifier header MUST ONLY be provided in an upgrade request, it MUST NOT be provided in the resource request.

If the server accepts the upgrade request, as specified in section 3.3 of RFC 2817, the client MUST authenticate the server. The client MUST construct a valid PKIX certificate path to a certificate that is signed using a public key whose hash matches the hash in the URL.

If the server does not accept the upgrade request, it SHOULD respond with a 3xx redirection. The Location response header MUST provide an http URL. The client MUST use this URL to retry the upgrade request, using the same Key-Identifier header. This redirection MUST NOT change the base URL for the resource request, nor modify the resource request that the client will send after the upgrade. In particular, the Host header in the resource request MUST contain the HTTP locator contained in the resource URL, not the locator in the redirection URL. The redirection is a redirection of the upgrade request only. The client SHOULD NOT automatically follow more than one redirection.

If the client is unable to successfully complete the upgrade request, it MUST produce an error. The resource request MUST ONLY be sent if the server is successfully authenticated.


[TLS] T. Dierks and C. Allen; "The TLS Protocol"; RFC 2246; January 1999.

[RFC 2817] R. Khare, S. Lawrence; "Upgrading to TLS Within HTTP/1.1"; RFC 2817; May 2000.

[RFC 2818] E. Rescorla; "HTTP Over TLS", RFC 2818; May 2000.

[RFC 2732] R.M. Hinden, B.E. Carpenter and L. Masinter; "Format for Literal IPv6 Addresses in URL's"; RFC 2732; December 1999.

[HTTP] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach and T. Berners-Lee; "Hypertext Transfer Protocol -- HTTP/1.1"; RFC 2616; June 1999.

[base32] T. Close; "WaterkenTM Enc -- base32 Encoding"; <http://www.waterken.com/dev/Enc/base32/>; June 2003.

[RFC 3279] W. Polk, R. Housley, L. Bassham; "Algorithms and Identifiers for the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile"; RFC 3279; April 2002.

[YURL] T. Close; "WaterkenTM YURL -- What Does the 'y' Refer to?"; <http://www.waterken.com/dev/YURL/Definition/>; June 2003.


Thanks to David Hopwood for his early and detailed review of this specification.


Copyright 2002 - 2003 Waterken Inc. All rights reserved.

Valid XHTML 1.0! Valid CSS!