Magic Signatures

Abstract

This document defines a lightweight, robust mechanism for digitally signing nearly arbitrary messages, along with a simple public key infrastructure.

It is intended to be a building block in the construction of protocols, providing a commonly agreed upon abstraction layer on top of lower level specifications such as Webfinger/LRDD (Eran, E., “LRDD: Link-based Resource Descriptor Discovery,” .) [LRDD], XRD (Eran, EHL. and WN. Will, “Extensible Resource Descriptor (XRD) Version 1.0, Working Draft 13,” .) [XRD], and PKCS (Jonsson, J. and B. Kaliski, “Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1,” February 2003.) [RFC3447]. It is not a complete protocol in itself, and requires that dependent protocols document the specific profile(s) used.

Table of Contents

1.  Introduction
    1.1.  Requirements Language
2.  Definitions
3.  Magic Envelope Definition
    3.1.  Magic Envelope Parameters
    3.2.  The Signature Base String
    3.3.  The Magic Envelope Compact Serialization
    3.4.  The Magic Envelope XML Serialization
    3.5.  The Magic Envelope JSON Serialization
4.  Standalone Magic Envelope Messages
    4.1.  Syndicating Magic Envelope Messages
5.  Encoding of data and sig using base64url
    5.1.  Encoding
    5.2.  Decoding
6.  The HMAC-SHA256 Private Key Signature Algorithm
    6.1.  Calculating the HMAC-SHA256 signature string
    6.2.  Signing and Verifying Messages with HMAC-SHA256
7.  The RSA-SHA256 Public Key Signature Algorithm
    7.1.  Signing Messages with RSA-SHA256
    7.2.  Verifying Messages with RSA-SHA256
8.  Magic Public Key Infrastructure
    8.1.  The application/magic-key MIME type
    8.2.  Discovery
        8.2.1.  The JSON Serialization of Magic Keys
        8.2.2.  The XRD XML Serialialization of Magic Keys
        8.2.3.  Discovery Flow
        8.2.4.  Key Selection
9.  Acknowledgements
10.  IANA Considerations
11.  Security Considerations
12.  References
    12.1.  Normative References
    12.2.  Informative References
Appendix A.  Specification Feedback
§  Authors' Addresses

1.  Introduction

The primary goal of Magic Signatures is to enable lightweight and robust public key signing for messages that may be transformed, converted, stored, and reconstituted in arbitrary ways. In order to make this mechanism useful, it also defines a public key discovery protocol that enables recipients to reliably map from URIs for signers to their public keys. It also allows for private key signatures, but leaves private key exchange mechanisms unspecified.

This mechanism is an alternative to XML Signature [XMLDSIG] (, “XML Signature Syntax and Processing (Second Edition),” .). Compared to XML Signature, Magic Signatures offers the following trade-offs:

1. Handles all payload data formats uniformly.
2. Does not require use of an XML processor for non-XML payloads.
3. Does not require any canonicalization beyond removal of whitespace, so it is much easier to verify messages correctly.
4. Can survive message disassembly, storage into arbitrary systems, and re-constitution without invalidating the signature (but it is not possible to sign only part of a message).
5. Significantly smaller and simpler specification.

Magic Signatures does not attempt to address every XML Signature use case, so it is best described as a lightweight, robust, and minimal form of digital signatures that can be used and deployed where XML Signatures has proven problematic in the field, for example feed syndication (see [RFC4287] (Nottingham, M., Ed. and R. Sayre, Ed., “The Atom Syndication Format,” December 2005.) section 5.1). Note that it is possible to combine both signature mechanisms if desired.

1.1.  Requirements Language

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 RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].

2.  Definitions

Signature:

A digital signature that provably binds a message to a signer's secret key.

Signer:

In this specification, an arbitrary URI used to determine a key used to sign an envelope. This specification does not dictate how signer URIs are to be determined, but in the usual case they are embedded within the signed data and extracted via a data format specific algorithm.

Public Key Infrastructure (PKI)

A set of hardware, software, people, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates. This specification uses a very simple, limited PKI.

3.  Magic Envelope Definition

A "Magic Envelope" comprises a message bundled along with signature(s) for that message, expressed as a series of parameters, and serialized as a compact string, JSON, or XML. The envelope specifies the data to be signed, the MIME type of the data, the transfer encoding, and the signature.

3.1.  Magic Envelope Parameters

This section describes the semantics of the parameters independent of the serialization used.

data:

The payload covered by the signature, encoded into an ASCII string. This string is guaranteed to be safe to include without escaping as XML text and in JSON strings. Appears exactly once.

data_type:

The MIME (Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies,” November 1996.) [RFC2045] type of the payload prior to encoding. Appears exactly once.

encoding:

The encoding used to convert between the MIME type and the "data" string. In this specification, encoding MUST be the string "base64url", indicating the url safe base64 encoding as described in RFC 4648 (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.) [RFC4648], sans any trailing padding with equals (=) characters, and with the additional whitespace normalization rules specified in Section 5.1 (Encoding). All implementations MUST support this encoding. Appears exactly once.

alg:

The algorithm used for the signature. This specification describes only one public key signature algorithm, "RSA-SHA256", and one private key signature algorithm, "HMAC-SHA256". Specifications relying on Magic Signatures MUST specify which of these MUST be supported for a particular protocol. Implementations of general Magic Signatures SHOULD support both for maximum interoperability. Appears exactly once.

sig:

A generated signature. This is a string in the base64url encoded format as described above. It is generated according to the rules for the "alg" in use. A Magic Envelope has one or more signatures. Each signature has at most one associated "key_id" parameter.

key_id:

Optional hint indicating which specific key owned by the signer should be used to verify the signature. This allows signers to explicitly signal a change of key to recipients. Omitting this parameter is equivalent to setting it to an empty string. The format of this parameter is unspecified except that all characters must be from the base64url allowed character set. Thus, "", "1", "AH478=", "0x6EF37D", and "fred" are all legal key_ids. The exact format is up to the key issuer. Note that any binary data can be converted into an acceptable key_id by base64url encoding it. One way to generate a usable key_id is to base64url-encode the SHA256 hash of the public signing key's magicsig representation; this allows a signer to provide usable ids without maintaining a mapping table.

3.2.  The Signature Base String

The Signature Base String used for both RSA-SHA256 and HMAC-SHA256 is described here. It is used as input to the signature algorithms, as well as to create the Compact Serialization (The Magic Envelope Compact Serialization), below.

Given a Magic Envelope with "data", "data_type", "encoding", and "alg" parameters, the corresponding Signature Base String is produced by concatenating the following substrings together, separated by periods (ASCII 0x2E):

1. The armored string for "data" produced by Section 5.1 (Encoding)
2. The Base64url encoding of the "data_type" parameter
3. The Base64url encoding of the "encoding" parameter
4. The Base64url encoding of the "alg" parameter

An omitted parameter is represented by a zero length placeholder string.

3.3.  The Magic Envelope Compact Serialization

The Magic Envelope Compact Serialization stores the envelope itself in a compact, armored form suitable for storage as a simple string. It is guaranteed to contain no spaces and no URL unsafe characters, and allows for only a single signature.

Given a singly signed envelope with one "sig" and one "key_id", the Compact Serialization is produced by concatenating the following substrings together, separated by periods (ASCII 0x2E):

1. The value of the "key_id" parameter
2. The value of the "sig" parameter
3. The Signature Base String as described in The Signature Base String (The Signature Base String), above.

For example, if the key_id is "4k8ikoyC2Xh+8BiIeQ+ob7Hcd2J7/Vj3uM61dy9iRMI=", the "sig" is "EvGSD2vi8qYcveHnb-rrlok07qnCXjn8YSeCDDXlbhILSabgvNsPpbe76up8w63i2fWHvLKJzeGLKfyHg8ZomQ", and the armored data is "Tm90IHJlYWxseSBBdG9t" with MIME type application/atom+xml, then the Compact Serialization would be the string: "4k8ikoyC2Xh+8BiIeQ+ob7Hcd2J7/Vj3uM61dy9iRMI=.EvGSD2vi8qYcveHnb-rrlok07qn CXjn8YSeCDDXlbhILSabgvNsPpbe76up8w63i2fWHvLKJzeGLKfyHg8ZomQ.Tm90IHJlYWxse SBBdG9t.YXBwbGljYXRpb24vYXRvbSt4bWw=.YmFzZTY0dXJs.UlNBLVNIQTI1Ng"

Any parameter MAY be omitted by leaving its slot empty, as indicated by two consecutive periods. When the "encoding" parameter is omitted, a recipient MUST decode the envelope as if it had the value "base64url". When the "alg" parameter is omitted, a recipient MUST interpret the message as if the "alg" parameter had the value "RSA-SHA256". The "data_type" parameter SHOULD NOT be omitted as it provides a defense against content type masquerading attacks.

3.4.  The Magic Envelope XML Serialization

A Magic Envelope XML Document is defined in terms of the XML Information Set, serialized as XML 1.0 [W3C.REC-xml-20040204] and identified with the "application/magic-envelope+xml" media type. Magic Envelope XML Documents MUST be well-formed XML. This specification does not define a DTD, and thus does not require validity (in the sense used by XML).

The following XML elements are in the namespace 'http://salmon-protocol.org/ns/magic-env', represented for brevity by the short prefix "me:" in the following definitions.

When used as a standalone XML document, the root element MUST be me:env. When incorporated as a subtree of another XML document, the root of the subtree MAY be an element specified elsewhere, with semantics documented by a specification relying on this one.

The parameters are mapped to XML elements and attributes as follows. Each parameter MUST appear exactly once per envelope.

The <me:data> element (REQUIRED):

Contains the "data" payload, an ASCII string, as described in Section 3.1 (Magic Envelope Parameters). The element contains one REQUIRED attribute, "type", which contains the value of the "data_type" parameter.

The <me:encoding> element (REQUIRED):

Contains the value of the "encoding" parameter.

The <me:alg> element (REQUIRED):

Contains the value of the "alg" parameter.

The <me:sig> element (REQUIRED):

Contains the value of the "sig" parameter, an ASCII string. MAY be repeated multiple times to record multiple signatures over the same text. MAY have a key_id attribute containing the "key_id" value for the signature.

Additional elements not defined by this specification MAY appear as children of any elements in this namespace. Processors MUST ignore elements they do not understand.

Example:

<?xml version='1.0' encoding='UTF-8'?>
<me:env xmlns:me='http://salmon-protocol.org/ns/magic-env'>
  <me:data type='application/atom+xml'>
    PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4KPGVudHJ5IHhtbG5zPS
    dodHRwOi8vd3d3LnczLm9yZy8yMDA1L0F0b20nPgogIDxpZD50YWc6ZXhhbXBsZS5jb20s
    MjAwOTpjbXQtMC40NDc3NTcxODwvaWQ-ICAKICA8YXV0aG9yPjxuYW1lPnRlc3RAZXhhbX
    BsZS5jb208L25hbWUPHVyaT5hY2N0OmpwYW56ZXJAZ29vZ2xlLmNvbTwvdXJpPjwvYXV0a
    G9yPgogIDx0aHI6aW4tcmVwbHktdG8geG1sbnM6dGhyPSdodHRwOi8vcHVybC5vcmcvc3l
    uZGljYXRpb24vdGhyZWFkLzEuMCcKICAgICAgcmVmPSd0YWc6YmxvZ2dlci5jb20sMTk5O
    TpibG9nLTg5MzU5MTM3NDMxMzMxMjczNy5wb3N0LTM4NjE2NjMyNTg1Mzg4NTc5NTQnPnR
    hZzpibG9nZ2VyLmNvbSwxOTk5OmJsb2ctODkzNTkxMzc0MzEzMzEyNzM3LnBvc3QtMzg2M
    TY2MzI1ODUzODg1Nzk1NAogIDwvdGhyOmluLXJlcGx5LXRvPgogIDxjb250ZW50PlNhbG1
    vbiBzd2ltIHVwc3RyZWFtITwvY29udGVudD4KICA8dGl0bGUU2FsbW9uIHN3aW0gdXBzdH
    JlYW0hPC90aXRsZT4KICA8dXBkYXRlZD4yMDA5LTEyLTE4VDIwOjA0OjAzWjwvdXBkYXRl
    ZD4KPC9lbnRyeT4KICAgIA
  </me:data>
  <me:encoding>base64url</me:encoding>
  <me:alg>RSA-SHA256</me:alg>
  <me:sig key_id="4k8ikoyC2Xh+8BiIeQ+ob7Hcd2J7/Vj3uM61dy9iRMI=">
    EvGSD2vi8qYcveHnb-rrlok07qnCXjn8YSeCDDXlbhILSabgvNsPpbe76up8w63i2f
    WHvLKJzeGLKfyHg8ZomQ
  </me:sig>
</me:env>

3.5.  The Magic Envelope JSON Serialization

Magic Envelope JSON MUST be well formed JSON as defined in [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.). The parameters are serialized into a JSON object as a sequence of name/value pairs for the parameter names "data", "data_type", "encoding", and "alg". These values are represented as JSON strings. The "sig" parameter is represented as a "sigs" name whose value is an array of objects; each object has a REQUIRED "value" with the signature string, and MAY have a "key_id" with the associated "key_id" parameter.

Additional name/value pairs MAY appear within the JSON object and processors MUST ignore elements they do not understand.

Example:

{
  "data": "
    PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4KPGVudHJ5IHhtbG5zPS
    dodHRwOi8vd3d3LnczLm9yZy8yMDA1L0F0b20nPgogIDxpZD50YWc6ZXhhbXBsZS5jb20s
    MjAwOTpjbXQtMC40NDc3NTcxODwvaWQ-ICAKICA8YXV0aG9yPjxuYW1lPnRlc3RAZXhhbX
    BsZS5jb208L25hbWUPHVyaT5hY2N0OmpwYW56ZXJAZ29vZ2xlLmNvbTwvdXJpPjwvYXV0a
    G9yPgogIDx0aHI6aW4tcmVwbHktdG8geG1sbnM6dGhyPSdodHRwOi8vcHVybC5vcmcvc3l
    uZGljYXRpb24vdGhyZWFkLzEuMCcKICAgICAgcmVmPSd0YWc6YmxvZ2dlci5jb20sMTk5O
    TpibG9nLTg5MzU5MTM3NDMxMzMxMjczNy5wb3N0LTM4NjE2NjMyNTg1Mzg4NTc5NTQnPnR
    hZzpibG9nZ2VyLmNvbSwxOTk5OmJsb2ctODkzNTkxMzc0MzEzMzEyNzM3LnBvc3QtMzg2M
    TY2MzI1ODUzODg1Nzk1NAogIDwvdGhyOmluLXJlcGx5LXRvPgogIDxjb250ZW50PlNhbG1
    vbiBzd2ltIHVwc3RyZWFtITwvY29udGVudD4KICA8dGl0bGUU2FsbW9uIHN3aW0gdXBzdH
    JlYW0hPC90aXRsZT4KICA8dXBkYXRlZD4yMDA5LTEyLTE4VDIwOjA0OjAzWjwvdXBkYXRl
    ZD4KPC9lbnRyeT4KICAgIA",
  "data_type": "application/atom+xml",
  "encoding": "base64url",
  "alg": "RSA-SHA256",
  "sigs": [
    {
    "value": "EvGSD2vi8qYcveHnb-rrlok07qnCXjn8YSeCDDXlbhILSabgvNsPpbe76
    up8w63i2fWHvLKJzeGLKfyHg8ZomQ",
    "key_id": "4k8ikoyC2Xh+8BiIeQ+ob7Hcd2J7/Vj3uM61dy9iRMI="
    }
  ]
}

4.  Standalone Magic Envelope Messages

The application/magic-envelope+{xml,json} data structures MAY be used standalone, as a drop-in replacement for the data that is encoded in the data element. This would be appropriate where the recipient understands the Magic Envelope specification and can automatically decode the data to recover the original format. For example, instead of POSTing an application/atom+xml type entry to create a new blog post, a client could POST an application/magic-envelope+xml with data of type application/atom+xml.

4.1.  Syndicating Magic Envelope Messages

It may be useful to syndicate Atom entries which have been enveloped and signed. This can be done in two ways: By adding a me:provenance element to the existing Atom entry and essentially duplicating its content in a signed me:data element, or by completely replacing each signed Atom entry with the corresponding me:env element.

Feed processors who understand Magic Signatures SHOULD treat me:env elements which verify correctly as if the underlying Atom entry had been sent. The semantics of me:env elements whose signatures cannot be verified are undefined by this specification; processors MAY ignore them, produce an error, attach a warning, or perform other actions as required by their security model. Specifications relying on this one SHOULD specify specific security models appropriate to their respective domains.

5.  Encoding of data and sig using base64url

The data and sig fields of a Magic Envelope are encoded as armored ASCII strings using a procedure chosen to be robust in the face of various types of transports and storage systems. Specifically, the encoded form is safe to include directly as text in XML, a string in JSON, a parameter in URLs, or as form data, without escaping. This section defines the mapping between arbitrary binary data (a stream of octets) and the armored form (an ASCII string). The ASCII string is also chosen so as to be a valid and equivalent UTF-8 string.

5.1.  Encoding

The basic procedure is to use the URL and Filename safe variant of the base64 encoding as described in RFC 4648 (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.) [RFC4648], section 5, hereafter known as "base64url" encoding. The result is a string that consists only of the ASCII alphanumeric characters along with '-' and '_', and possibly '='. In regular expression form, this is "^[A-Za-z0-9\-_]*=?=?=?$". This is the normalized form of the encoded data, and is the basis for the octet sequence that is used to generate the digital signature. Implementations and transports MAY add arbitrary whitespace (ASCII values 0x09-0x0D and 0x20) anywhere in this string after signing but before output so as to, e.g., comply with line length restrictions in certain environments.

5.2.  Decoding

The basic procedure is the reverse of encoding, with the additional step that whitespace from the input should be ignored. This is necessary for robustness because some transports may insert whitespace, and is useful to allow for human readable formatting of documents in any case.

1. Normalize the string by removing all whitespace characters from input.
2. Base64url decode the resulting string to produce the original binary data.

6.  The HMAC-SHA256 Private Key Signature Algorithm

This section defines a basic HMAC based private key signature algorithm. HMAC key exchange and rotation is outside the scope of this specification, but may be defined in specifications relying on this one.

6.1.  Calculating the HMAC-SHA256 signature string

First, create an HMAC-SHA256 signature using the algorithm described in RFC 2104 (Krawczyk, H., Bellare, M., and R. Canetti, “HMAC: Keyed-Hashing for Message Authentication,” February 1997.) [RFC2104], using SHA-256 as the hash function H, base string described in Section 3.2 (The Signature Base String) as the input text, and the shared secret key K. The resulting array of bytes is then base64url encoded to produce the "sig" parameter.

6.2.  Signing and Verifying Messages with HMAC-SHA256

Signing consists of calculating the "sig" parameter and serializing it along with the other parameters to create a Magic Envelope. Verifying consists of re-calculating the expected "sig" parameter given the other parameters, and doing an exact string comparison of the "sig" parameters after normalization (whitespace removal).

7.  The RSA-SHA256 Public Key Signature Algorithm

This section defines the default public key signature algorithm for Magic Signatures. In addition to indicating the signing algorithm, use of RSA-SHA256 by default also implies use of the Magic Public Key Infrastructure Section 8 (Magic Public Key Infrastructure) to obtain public keys. Specifications relying on Magic Signatures MAY specify other mechanisms for key retrieval.

7.1.  Signing Messages with RSA-SHA256

Signing a message consists of signing the contents of "data", "data_type", "encoding", and "alg" using the chosen algorithm. This section defines the "RSA-SHA256" algorithm, meaning the RSASSA-PKCS1-v1_5 signature algorithm from RFC 3447 (Jonsson, J. and B. Kaliski, “Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1,” February 2003.) [RFC3447] section 8.2, also known as PKCS#1, using SHA-256 as the hash function for EMSA-PKCS1-v1_5.

Note: As best current crypto practices change, new algorithms will become available and both extensions and future revisions of this specification may include additional new public key algorithms (e.g., RSASSA-PSS). When both clients and servers have sufficiently widespread support for the latest algorithm, older algorithms (e.g., RSASSA-PKCS1-v1_5) will be deprecated and removed in subsequent revisions of this specification.

The signature is computed as signature_octets = RSASSA-PKCS1-V1_5-SIGN (K, M), where K is the private signing key and M is the Signature Base String (The Signature Base String) defined above. Thus M is produced by concatenating the following substrings together, separated by periods (ASCII 0x2E):

1. The armored string for "data" produced by Section 5.1 (Encoding)
2. The Base64url encoding of the "data_type" parameter
3. The Base64url encoding of the "encoding" parameter
4. The Base64url encoding of the "alg" parameter

For example, if the armored data is "Tm90IHJlYWxseSBBdG9t" with MIME type application/atom+xml, then M would be the string: "Tm90IHJlYWxseSBBdG9t.YXBwbGljYXRpb24vYXRvbSt4bWw=.YmFzZTY0dXJs.UlNBLVNIQTI1Ng"

For convenience we summarize the steps for the required EMSA-PKCS1-v1_5 with RSA-SHA256 algorithm here. In the following, '+' means string concatenation.

1. Let hash = the SHA256 hash digest of M
2. Let prefix = the constant byte sequence [0x30, 0x31, 0x30, 0xd, 0x6, 0x9, 0x60, 0x86, 0x48, 0x1, 0x65, 0x3, 0x4, 0x2, 0x1, 0x5, 0x0, 0x4, 0x20]
3. Let k = the number of bytes in the public key modulus
4. Let padding = '\xFF' repeated (k - length(prefix+hash) - 3) times
5. Let emsa = '\x00' + '\x01' + padding + '\x00' + prefix + hash
6. RSA sign the emsa byte sequence

The signature is then encoded as in Section 5.1 (Encoding) and the resulting ASCII armored string stored as a "sig" signature. The associated "key_id" is the key_id associated with that signing key and published per Section 8 (Magic Public Key Infrastructure). If the signer does not maintain individual key_ids, it SHOULD output the base64url encoded representation of the SHA-256 hash of public key's application/magic-key representation.

7.2.  Verifying Messages with RSA-SHA256

Verifying a message signature consists of verifying that "sig" is a valid signature for "data" using "alg". This specification defines only the "RSA-SHA256" verification algorithm, meaning the RSASSA-PKCS1-v1_5 verification algorithm from RFC 3447 (Jonsson, J. and B. Kaliski, “Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1,” February 2003.) [RFC3447] section 8.2.1.

The verification is performed by executing RSASSA-PKCS1-V1_5-VERIFY ((n, e), M, S), where (n ,e) comprise the public key, M is the message string documented in Section 7.1 (Signing Messages with RSA-SHA256), and S is the decoded value of a selected "sig". (Note that this algorithm creates the emsa byte sequence as in Section 7.1 (Signing Messages with RSA-SHA256) and then performs RSA verification using (n, e), emsa, and S.)

The scope of the verification covers only the contents of the Magic Envelope itself. In some cases, the information from the decoded "data" value must be checked against or override the enclosing data. The mechanisms for this are specific to the kinds of data, but in general a secure if lossy mechanism is to throw away the unverified information and replace it with the output of the decoded "data". The correct mechanism depends on the security model required by the processor and is outside the scope of this specification.

It is RECOMMENDED that signed content contain expiration information after which the signed data SHOULD NOT be verified or used without additional confirmation. Such confirmation is outside the scope of this specification. However, when this is done and signing keys also expire on a predictable time in the future, signers SHOULD ensure that the content expiration is not after the known key expiration time. That is, the signed content should expire no later than the expiration date of the key used to sign it.

Note that emergency key revocation is outside the scope of this specification. However, implementations SHOULD honor HTTP cache control directives when retrieving key material and SHOULD NOT use keys for verification without revalidating the content as directed by the origin server. This allows origin servers to trade off performance for smaller periods of vulnerability.

Unless specified otherwise, the public key (n, e) is obtained using the simple public key infrastructure described by Section 8 (Magic Public Key Infrastructure). Note that several candidate signing keys may be retrieved, and in the worst case verifiers MUST try each one with equal key_id until at least one successfully verifies the signature. Two key IDs are equal if their individual octets are equal and they are of equal length. A signature with an empty (missing) key_id, which may have been signed by any key, MUST be verified against all available keys.

8.  Magic Public Key Infrastructure

This section defines a public key infrastructure based on URIs. It uses LRDD discovery plus direct retrieval via secure URLs. Specifically, given a signer URI such as "acct:bob@example.com" or "http://example.com/bob", the corresponding public key(s) for that identifier can be found discovery as defined below. The result is a set of RSA public keys in a simple string format.

8.1.  The application/magic-key MIME type

The application/magic-key format is a very minimal format for representing public key data. It consists of a string of ASCII text, separated into 3 components, with components separated by a "." (0x2E) character. The first component is the key type; this specification only defines the "RSA" key type for future upgradeability. Thus a magic key consists of the string "RSA.modulus(n).exponent(e)"; for example:

RSA.mVgY8RN6URBTstndvmUUPb4UZTdwvwmddSKE5z_jvKUEK6yk1u3rrC9yN8k6FilGj9K0eeUPe2hf4Pj-5CmHww.AQAB

The pair (n, e) is used as input to RSASSA-PKCS1-V1_5-VERIFY.

Each of the components is first represented as an integer in network byte order (big endian), with no leading zero bytes, and encoded via the "base64url" mechanism described in Section 3.1 (Magic Envelope Parameters).

This specification defines only a public key format, and anticipates that keypairs may be stored securely in other formats (e.g., DER encoded X.509 certificates) and that the application/magic-key data will be generated via tools.

8.2.  Discovery

This section defines how to map from a signer URI identifier to a set of public signing keys for that identifier. The exact mechanism for a verifier to determine the signer URI is outside the scope of this specification, and MUST be specified by the particular protocol or application of Magic Signatures. The URI identifier MUST appear within, or be derived from, information within the "data" parameter and therefore be covered by the signature.

Many existing formats contain authorship, sender, or issuer fields and these SHOULD be used or extended where possible. Protocols which rely on Magic Signatures for digital signatures MUST specify a format-dependent model for determining potential signer URIs given the signed data. This section describes the subsequent discovery step: How to take a general URI and securely map it to a set of public signing keys with optional key ids.

The end result of discovery will be a collection of magic keys. Each magic key has a "data" parameter, a string in application/magic-key format; and an optional "key_id" parameter, a string as defined below. If the key_id is omitted from a key, it defaults to the Base64url encoding of the SHA-256 hash of the "value" parameter. That is, when doing discovery, processors MUST assume that an omitted key_id is equivalent to specifying key_id = Base64url(SHA-256(value)). A signer MAY then use this value as a key_id on a signature in order to signal use of that key.

There are two standard serializations of this collection, one for JSON and one for XML. Both are intended to be embeddable within general discovery metadata.

8.2.1.  The JSON Serialization of Magic Keys

The keys are stored within an array named "magic_keys". The array's values are objects, each of which MUST have a string "value" element containing the application/magic-key string, and which MAY have a string "key_id" element containing the id of that key.

Example:

{
  "magic_keys": [
    {"value": "RSA.mVgY8RN6URBTstndvmUUPb4UZTdwvwmddSKE5z_jvKUEK6yk1u3rrC9yN8k6FilGj9K0eeUPe2hf4Pj-5CmHww.AQAB",
     "key_id": "1"},
    {"value": "RSA.wvwmdK0eeUPe2hURBTstndvmUUPb4UZTd6wvwmddSrrC89yN8k6FilGwvwmddSKE5z_jvKUEKj9f4Pj-5CmHww.AQAB",
     "key_id": "2"}
  ]
}

8.2.2.  The XRD XML Serialialization of Magic Keys

The keys are stored as XRD Property elements within the XRD document. The type of the Property element is "http://salmon-protocol.org/ns/magic-key" and this is also the XML namespace of dependent elements and attributes. Each one has an optional mk:key_id attribute containing the key's id; the body of the Property element contains the application/magic-key string data.

Example:

<Property xmlns:mk="http://salmon-protocol.org/ns/magic-key"
          type="http://salmon-protocol.org/ns/magic-key"
          mk:key_id="1">
  RSA.mVgY8RN6URBTstndvmUUPb4UZTdwvwmddSKE5z_jvKUEK6yk1u3rrC9yN8k6FilGj9K0eeUPe2hf4Pj-5CmHww.AQAB
</Property>
<Property xmlns:mk="http://salmon-protocol.org/ns/magic-key"
          type="http://salmon-protocol.org/ns/magic-key"
          mk:key_id="2">
  RSA.wvwmdK0eeUPe2hURBTstndvmUUPb4UZTd6wvwmddSrrC89yN8k6FilGwvwmddSKE5z_jvKUEKj9f4Pj-5CmHww.AQAB
</Property>

8.2.3.  Discovery Flow

Given a URI U, first perform discovery on U per Webfinger/LRDD (Eran, E., “LRDD: Link-based Resource Descriptor Discovery,” .) [LRDD] and interpret the result per the XRD XML Serialization. If this step produces a set of keys, stop. Otherwise, if U is an https URL, directly retrieve the resource U via SSL, performing necessary certificate checks, and see if the resulting data is of type application/metadata+json. If so, look for the "magic_public_keys" array as per the JSON Serialization. If both of these steps fail to produce a set of keys, stop.

8.2.4.  Key Selection

Once a set of possible key candidates have been determined, via discovery or alternatively via an extension mechanism outside the scope of this specification, a verifier must then determine whether a given signature is valid. This section details how to do so in an interoperable way.

Among the available keys, select the key for verification by matching the key_id against the key_id specified in the signature. In this context an empty string key_id matches everything. This produces a smaller set of possible keys to use for verification. Verification succeeds if any one of these keys successfully verifies the signature.

Note that in the case of multiple signatures, it is possible for one signature to be verified but for others to fail. Specifications relying on Magic Signatures MUST specify the semantics in these cases.

9.  Acknowledgements

This document is the outcome of meetings and feedback from a large number of people. In particular, feedback from the Federated Social Web, Webfinger, OAuth, Activity Streams, and Salmon Protocol communities has been invaluable. Some of the people who contributed to this effort are:

Bob Aman, Darren Bounds, Charlie Cauthen, DeWitt Clinton, George Fletcher, Hunter Freyer, Eran Hammer-Lahav, Timothy Jordan, Mike Macgirvin, James Manger, Sean McCullough, Breno de Medeiros, Chris Messina, Will Norris, Ade Oshineye, NeilFred Piccolo, Evan Prodromou, Arne Roomann-Kurrik, Brett Slatkin, Joseph Smarr, James Snell, Brian Stoler, James Walker, Stephen Paul Weber, Bob Wyman.

The authors apologize for any omissions from this list, which are certainly unintentional.

10.  IANA Considerations

This specification introduces three new media types.

The MIME media type for the XML serialization of a Magic Envelope is application/magic-env+xml.

Type name: application

Subtype name: magic-env+xml

Required parameters: n/a

Optional parameters: n/a

The MIME media type for the unique JSON serialization of a Magic Envelope is application/magic-env+json, though application/json is also appropriate.

Type name: application

Subtype name: magic-env+json

Required parameters: n/a

Optional parameters: n/a

The MIME media type for key(pairs) is application/magic-key.

Type name: application

Subtype name: magic-key

Required parameters: n/a

Optional parameters: n/a

11.  Security Considerations

Specific security considerations are embedded in the relevant functional sections above. In general, with reference to [RFC3552] (Rescorla, E. and B. Korver, “Guidelines for Writing RFC Text on Security Considerations,” July 2003.), Magic Signatures is a message oriented security protocol that provides object level data integrity and data origin (sender) authentication. It leaves other security considerations, and specific threat models, to relying specifications. In particular, note that:

1. Core Magic Signatures addresses neither confidentiality nor replay attacks. Relying specifications SHOULD address these issues as appropriate, e.g., by ensuring that messages are idempotent.
2. Magic Signatures defines only a basic set of key validity checks. A key which passes these checks may still be invalid for other reasons (e.g., if it has been revoked by some mechanism outside the scope of this specification). Specifications relying on Magic Signatures SHOULD specify additional validity checks as appropriate.
3. Magic Signatures relies on the existence of a reliable domain name service and TLS for bootstrapping domain-level discovery information, and is dependent on the proper end-to-end implementation of TLS, including operational security of web servers, avoiding non-TLS redirects, honoring certificate revocation lists, and maintaining an appropriate set of trusted root CAs. Leveraging DNSSEC, when available, to reduce the CA attack surface is RECOMMENDED.
4. Magic Signatures leaves other security issues for relying specifications.

12.  References

12.1. Normative References

12.2. Informative References

Appendix A.  Specification Feedback

The primary driver of this specification is the Salmon protocol. Feedback on this specification is thus welcomed via the salmon-discuss mailing list, salmon-protocol@googlegroups.com. For more information, see the Salmon discussion group. Bugs and errata may also be reported via the Salmon bug tracker.

Authors' Addresses