No Working GroupA. Alice
Internet-DraftJuly 30, 2003
Expires: January 28, 2004 

The "crypto" URL scheme

Status of this Memo

This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

The list of current Internet-Drafts can be accessed at

The list of Internet-Draft Shadow Directories can be accessed at

This Internet-Draft will expire on January 28, 2004.

Copyright Notice

Copyright (C) The Internet Society (2003). All Rights Reserved.


This document defines a URL scheme for attaching "crypto data" (such as document hashes, key fingerprints, and key URLs) to an underlying URL. The resultant "cryptoURL" contains everything needed for authenticated, and perhaps confidential, communications with the underlying resource.


Table of Contents


1. Introduction

This document defines a URL scheme for attaching "crypto data" (such as document hashes, key fingerprints, and key URLs) to an underlying URL. A normal URL contains everything needed to access a resource. A "cryptoURL" contains everything needed to access a resource securely. At a minimum, this means that you can access the underlying URL with the assurance that your communications are not being tampered with.

A cryptoURL may provide stronger guarantees. It may guarantee that you are seeing the exact same bytes as the creator of the cryptoURL. It may also enable confidential communications with the resource. But all cryptoURLs at least prevent active attacks on the communication channel.

Some example cryptoURLs:




2. Categories of cryptoURLs

Depending upon the types of crypto data they contain, cryptoURLs fall into one (or more) of three categories:

Strongly-hashed cryptoURLs:
Contain a strongly collision-resistant hash on the resourceís contents.
Weakly-hashed cryptoURLs:
Contain a 2nd-preimage-resistant hash on the resourceís contents.
Fingerprinted cryptoURLs:
Contain a 2nd-preimage-resistant hash on the resourceís public key, or some data by which the public key can be ascertained.

A strongly-hashed cryptoURL gives the strongest guarantee: unless the hash algorithm is broken, you are guaranteed that the resource has resolved to the exact same contents it had for the creator. SHA-256 or SHA-512 give strongly-hashed cryptoURLs.

A weakly-hashed cryptoURL gives a weaker guarantee: unless the hash algorithm is broken, you are guaranteed that the resource has resolved to some contents known to the creator at the time of creation, but there may be multiple such contents that give the same hash, allowing the creator to switch them while leaving the cryptoURL unchanged. Weakly-hashed cryptoURLs are shorter than strongly-hashed cryptoURLs, and can use hash algorithms like SHA-1 and MD5 that are widely deployed.

A fingerprinted cryptoURL gives the weakest guarantee: even if the hash and public key algorithms arenít broken, and the private key hasnít been compromised, the keyholder can present whatever resource contents he wants. Of course, this flexibility is necessary for URLs that contain dynamic content. Unlike hashed cryptoURLs, fingerprinted cryptoURLs typically offer confidentiality as well as authentication.


3. Use Cases

Possible uses for cryptoURLs include:

Software Downloads:
Webpages often reference software downloads from mirror sites. To ensure these files arenít trojanized, the pages often present MD5 hashes. If these hashes were incorporated into cryptoURLs, they could be automatically checked by the browser after downloading.
Signed Documents:
A signed HTML or XML document might contain URL references to other documents. If these were linked with strongly-hashed cryptoURLs, then the signature would extend over the referenced documents.
Application Configuration:
Software often needs to be configured to know about network services. For example, an application might need to know about an XKMS responder, or some other web service. Fingerprinted cryptoURLs could be a standard format for configuring software with both the address of a server and its key fingerprint.
Encrypted Email:
People often make their email public key (i.e. PGP key, or S/MIME certificate) available on their website. With a fingerprinted cryptoURL that includes a URL and hash for the key, you could prepare to send them a secure email with a single click.
Server Referrals:
LDAP and IMAP servers return URL referrals when the client tries to access a resource which is stored elsewhere. If these were fingerprinted cryptoURLs, then the client could securely access the remote resource.
Website Links:
Websites might link to each other with fingerprinted or hashed cryptoURLs. For example, a trusted portal could provide secure access to a community of sites.


4. Syntax

A cryptoURL consists of an underlying URL or URL reference followed by comma-separated type=value pairs in brackets. For example:


A cryptoURL can be parsed using the following ABNF, along with the URI-reference rule from RFC 2396bis:

cryptoURL = "crypto:" URI-reference "[" crypto-data "]"

crypto-data = crypto-datum *( "," crypto-datum )

crypto-datum = crypto-type "=" crypto-value

crypto-type = *crypto-char

crypto-value = *crypto-char

crypto-char = unreserved / escaped / "/" / "?" / "#" / ";" / ":" / "@" / "&" / "+" / "$"

Certain crypto-types may take URLs as values. In that case, any occurence of the characters "[", "]", "=", and "," in the URL MUST be encoded.

Certain crypto-types may take binary data as values. In that case, the value will be hex-encoded in dot-separated groups of four, using lowercase hex characters, for ease of reading and transcription:



5. Processing of Crypto Data

Section 6 describes certain crypto-types and how they should be interpreted with certain URL schemes. Additional crypto-types may be registered with the IANA, per section 7. Future RFCs can define interpretations that extend pre-existing crypto-types to additional URL schemes.

A cryptoURL is always processed under some profile. The default profile requires the processor to understand and validate every crypto-type in the cryptoURL. Application contexts may define more specific profiles. For example, a profile for using cryptoURLs in an XML-DSIG signed document might require the content_sha256 crypto-type, and would ignore other crypto-types.

Certain crypto-types may affect the processing of the immediately subsequent crypto-types. We will consider the result a "compound" crypto-type, where the initial crypto-type is the "head" and those following it are the "tail". Newly introduced head crypto-types should not take pre-existing crypto-types in their tail, otherwise an application might not recognize and thus ignore the head, and as a result process the tail incorrectly. Similarly, applications should not add support for tail crypto-types without also supporting all the head crypto-types that may take this type as a tail.


6. Types of Crypto Data

content_md5, content_sha1, content_sha256:
SHA-256 creates a strongly-hashed cryptoURL, the others create weakly-hashed ones. They take a binary value, which is the hash calculated on the resource after it has been retrieved and any transfer encoding has been stripped off. When these datatypes are present, a content_type crypto-value may also be present. If the content_type is of type ďtextĒ, line breaks will be normalized to LF (0xA) characters before hashing.

These datatypes can be applied to http, https, ftp, or file URLs. They could possibly be applied to schemes like news, imap, or ldap, but the utility of that is less clear. Of course, private or future URI schemes could define the use of these datatypes in their context.

When used with http(s), ftp, and file schemes, these datatypes may not be repeated (i.e. such a cryptoURL may not have multiple hash values using the same algorithm). A hashed cryptoURL with a relative underlying URL should verify properly regardless of the access scheme, since the hash only depends on the resourceís contents.

This can be used in a hashed cryptoURL to give the MIME type of the resourceís contents, represented as per RFC 2397 section 3. This value serves two purposes. First, it may indicate that the contents should be canonicalized before hashing. Currently, the only canonicalization we consider is normalizing line breaks to LF (0xA) characters for any text type.

Second, if the underlying protocol in a hashed cryptoURL also carries a representation of the content type (such as the Content-Type field in an HTTP response), then this datatype MUST be present, and its value MUST be compared against the protocolís value, to prevent an attacker from changing the protocolís value and thus causing the contents to be interpreted incorrectly.

The comparison should consider that the content typeís type, subtype, and parameter names are not case-sensitive, but the parameter values are, and that parameter ordering and whitespace between parameters is irrelevant, as are quotes around the parameter values.

This is a fingerprint constructed by hashing an X.509 certificate. It will typically indicate a certificate thatís used with TLS/SSL (for https, ldap, pop, smtp, or any other scheme using TLS/SSL for security), or S/MIME (for mailto). Multiple instances of this datatype may occur in a cryptoURL (for example, a mailto URL may have both a signing and encryption certificate). A party relying on this datatype should check that a received certificate matches one of the instances, then extract and use the public key. The party should consider the public key acceptable regardless of certificate fields like subject name, policies, validity interval, and so on. For a noninteractive protocol like S/MIME, however, where the party must choose which certificate to use without being presented with one, the party may consider certificate fields (for example, to differentiate a signing from encryption certificate).

This crypto-type refers to the preceding x509_sha1 crypto-type, and gives the URL where that certificate can be retrieved (per RFC 2585). There may be multiple instances of this type following a single x509_sha1 for redundancy in case one becomes unreachable. This crypto-type will be used for noninteractive protocols (like S/MIME) where the party processing the cryptoURL must acquire the end entity certificate by himself.

This is a fingerprint for a CA certificate (perhaps self-signed, perhaps not). It can be used in the same circumstances as x509_sha1. This certificate is used as a trust anchor to validate a certificate chain to an end entity certificate for the resource. The end entity certificate must contain a name matching the URL. For example, an end entity S/MIME certificate used in the mailto scheme must certify the email address, and a TLS certificate must certify the serverís name.

This type of crypto data places more of a burden on the relying party than the x509_sha1 datatype, since the relying party must be capable of X.509 path validation. But it has some advantages: first, if the end entity certificate is revoked, the relying party can detect this (by retrieving the CRL indicated in the end entity certificateís CDP extension). Second, if the certificate expires or is revoked, the end entity can get a new certificate that will continue to match this cryptoURL, whereas a cryptoURL with an x509_sha1 value will be invalidated by such a change.

This refers to the preceding x509_root_sha1 crypto-type, and will give the URL where that certificate can be retrieved (per RFC 2585). There may be multiple instances of this type following a single x509_root_sha1, for redundancy in case one becomes unreachable. This crypto-type may need to be used for interactive protocols, like TLS, which have the option of omitting the trust anchor of the transmitted certificate chain.

This refers to the preceding x509_sha1 or x509_root_sha1 crypto-type, and will give the URL where a certificate chain can be retrieved that matches either the x509_sha1 end entity certificate or the x509_root_sha1 CA certificate. The URL points to a certs-only instance of Application/pkcs7-mime per RFC 2633. This crypto-type will be used for noninteractive protocols (like S/MIME) where the party processing the cryptoURL must acquire the end entity certificate by himself.

This gives the fingerprint of a PGP key, for use in the mailto scheme. There should only be a single occurrence of this data type in a cryptoURL.

This gives a URL where the preceding PGP key can be downloaded (as a plain text file).


7. IANA Considerations

New crypto-types require review by a Designated Expert. Interpretations that extend a crypto-type to a new protocol are the responsibility of whoever is authoritative for that protocol.




Author's Address



Intellectual Property Statement

Full Copyright Statement